WebAPI/WebPrintAPI

First iteration: WebPrintAPI

Scope

This is about implementing a new API for printing on the web. It's a "low level" API that allows web developers to have more control over printing output.

Defining the PrintSetting API as used in PrintDocument.print(printSetting) is out of the scope of this document.

Notes

• Use points as metric for printing (72 points per inch)
• Use of "px" doesn't make sense. Therefore they are forbidden (e.g. in font-size="12px") - use "pt" instead.
• Use of ctx.putImageData(...) and ctx.getImageData(...) doesn't make sense as there might not be something like "pixels" on the printer backend.
• If the user selects File -> Print from the menu, the developer can skip the printing listening to the window.onBeforePrint, create a PrintDocument object and print this one. This allows "custom" page printing as you could expect it to be inside some apps (Google Docs etc).
• There is only one page size per PrintDocument.
• The size of the page is defined within the PrintDocument constructor. If the defined page size doesn't fit the printer's page size, the content get's aligned as specified by the 'scale' property (see below).

Open Questions

• What is (0,0)? The top left corner of the physical page OR of the page taking into account the print margin?
• Should there be different color spaces then RGB? There is a <a href="http://www.w3.org/TR/css3-gcpm/#cmyk-colors">proposal for CMYK colors in CSS</a>.
• Should the browser display a progress view while the pages are drawn (this doesn't mean the actual printing output progress)?
• Should there be additional onBeforePrint/onAfterPrint callbacks on the PrintDocument object, or are the window.onBeforePrint/onAfterPrint events enough?
• This proposal assumes the print page size is passed during the PrintDocument constructor. A different way is to get the page size from the current selected printer's page size. Defining the page size once makes things easier but makes this API on the other side less powerful.
• Lot more... TBD

Possible values for the 'scale' property (see below)

• 'scale': Scales the drawing while keeping the ration to to fit on the print paper size
• 'fit': Scales the drawing while not taking the ration of the printer paper size in account
• 'center': No scaling, just placing the center of the drawing onto the center of the printer paper.

Example

 var pDoc = new PrintDocument(
                 'documentTitle',  // Title
                 'letter',         // Paper size
                 'scale',          // optional: see notes about "scale"
                 false             // optional: isLandscape?
               );
               
 // ---
 // Following functions MUST be defined by the developer.
 // ---
 
 // The number of pages to print.
 pDoc.calcPageCount = function(fontCtx) {
   var pageCount;
   
   // ..
   
   // The fontCtx is a very limited subset of the normal print ctx, that
   // is just about doing text measurements.
   fontCtx.font = '...';
   fontCtx.measureText(...);
   
   //...
   
   return pageCount; // 42
 };
 
 // Actually drawing function. Each page is drawn individually. This is
 // handy for page preview or if the user picks only a subset of the total
 // pages.
 pDoc.renderPage = function(pageNumber, ctx) {
   if (ctx.isPreview) {
     var dpi = ctx.dpi;
     
     // Only draw images in low resolution for preview
     // ...
   }
   
   // Render the page <pageNumber> to the ctx.
   ctx.draw...
   // ...
   
   // If the drawing takes very long, the developer might want to use
   // setTimeouts and continue the painting later one.
   if (printingWillTakeLong()) {
     setTimeout(function() {
       // Continue drawing...
       
       // This page is done drawing.
       ctx.endPage();
     })
   } else {
     ctx.endPage();
   }
 }
   
 // ---
 // Following functions/properties are implemented by the
 // WebPrintAPI. They are listed here only to get an idea what they
 // will return.
 // ---
 
 // Getter:
 pDoc.pageSize = {
   <widthInInch>,
   <heightInInch>,
 }
 
 // Getter:
 pDoc.unwriteableMargin = {
   top:    <inch>,
   bottom: <inch>,
   left:   <inch>,
   right:  <inch>
 }
 
 // Was the printing started but is not finished yet?
 pDoc.isPrinting;
 
 // Are all the pages drawn?
 pDoc.isFinished;
 
 // Start the printing progress. This opens the print dialog.
 // The passed in `printSetting` is not defined yet and is outside of the scope
 // of this proposal/API.
 pDoc.print(printSetting);
 
 // Stops the print process. Once all data is created, there is no way to stop
 // the printing anymore; that means, as soon as `pDoc.isFinished` is true,
 // calling this function has no effect.
 pDoc.abort();

Proposed API

See the example to get an idea. More details coming soon!

Implementation

Some basic investigation in the Gecko codebase. No code written so far.