Understanding the printout lifecycle

You start a printing session by creating an instance of your printout object, and also an instance of the class wx.Printer.

wx.Printer(data=None)

The optional data parameter is an instance of wx.PrintDialogData. To start the actual printing, call the Print(parent, printout, prompt=True) method of wx.Printer. The parent parameter is the parent window for the printing (it's used as the parent window for any dialogs that are invoked). The printout parameter is your wx.Printout instance. If the prompt parameter is True, wxPython will display the printer dialog before printing, otherwise it will not.

After the Print() method starts, it calls the first of the overridable methods of wx.Printout, OnPreparePrint(). The prepare method is guaranteed to be called before the wx.Printout instance does anything else, so it's a good place to gather your data or do any calculations that need to be done before printing begins. The actual printing begins with the OnBeginPrinting() method, which you can also override for custom behavior if you want—by default, the method does nothing. The OnBeginPrinting() method will be called only once for the entire print session.

Each individual copy of the document that you wish to print triggers one call of OnBeginDocument (startPage, endPage), where startPage and endPage are integer arguments telling wxPython what pages of the document to print. Both arguments are inclusive. If you override this method, you must call the base class method because it does some important accounting (such as calling wx.DC.Start-Doc()). In wxPython, you call the parent method with the line base_OnBegin-Document(startPage, endPage). Returning False from OnBeginDocument will cancel the print job.

The method you are most likely to override is OnPrintPage(pageNum), which is where you place your drawing commands for each page. The pageNum argument is the number of the page to print. Within this method, you call GetDC(), which returns an appropriate device context, depending on your current system platform. For actual prints, the instance you get is of the class wx.PrinterDC if you are on an MS Windows system. On any other system, the instance is of the class wx.PostScriptDC. If you are inside a print preview operation, you get a wx.MemoryDC for any operating system. Once you have the device context, you can make any device context drawing operations you want, and they will be printed or previewed appropriately.

After the pages are printed, the events unwind. At the end of each copy, a call to OnEndDocument() is triggered. Again, if you override this method, you must call the base class method with the line base_OnEndDocument(). This calls the wx.DC.EndDoc() method. And, when all your copies are done, the OnEndPrint-ing() method is called, finishing the print session.

There is one other overridable method of wx.Printout, which you will usually need to override and which is used by the printing framework for loop control. The method HasPage(pageNum) returns True if the integer pageNum is within the document and False otherwise. The default is to return True only when pageNum == 1.

+1 0

Post a comment