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 rich control about 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.
• 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)?
  • 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();
   }
 }
 
 // ---
 // Provided API functions
 // ---
 
 // 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.