Gecko:Printing API

Editors

Tobias Schneider

Scope

Purpose of this document is to define a set of standards and API's to give web developers more control over printing output.

Example

// Gets fired after user clicked File->Print.
window.onprint = function (e) {
	customPrint();
	// Event can and should be canceled.
	e.preventDefault();
};

function customPrint() {
	// By calling startPrintJob, the Browser opens the system printing dialog.
	// After the user clicks the print button, the print page handler gets
	// called for every page in the user defined range and returns a Promise
	// that resolves to a HTML element to be printed on that page.
	//
	// A final Promise is returned by startPrintJob which resolves after
	// successfully printing all pages, or rejects if one of the page promises
	// was rejected, an error occured during rendering or if the printing was
	// canceled by the user.
	window.startPrintJob(function (state) {
		var canvas = document.createElement("canvas");
		var ctx = canvas.getContext("2d");
		if (!state.isPreview) {
			// We can draw at higher resolution for actual printing output.
			canvas.width *= 5;
			canvas.height *= 5;
			ctx.scale(5, 5);
		}
		switch (state.currentPage) {
			case 1:
				ctx.drawText(0, 0, state.title);
				break;
			case 2:
			case 3:
				ctx.drawText(0, 0, "Page " + state.currentPage + " of " + state.totalPages);
				break;
			default:
				return Promise.reject(Error("Invalid page number"));
		}
		return Promise.resolve(canvas);
	}, /* Total number of Pages */ 3, /* Document title */ "Printing Example")
	.then(function () {
		console.log('Printing was successful');
	}, function () {
		console.error('Printing failed');
	});
}

IDL additions

interface WindowEventHandlers {
	attribute EventHandler onprint;
	...
};

interface PrintPageHandler {
	Promise getPageElement(PrintState state);
};

interface PrintState {
	readonly attribute double totalPages;
	readonly attribute DOMString title;
	readonly attribute double currentPage;
	readonly attribute boolean isPreview;
};

dictionary PrintOptions {
	double totalPages	= 1;
	DOMString title 	= null;
	...
};

interface WindowPrinting {
	Promise startPrintJob(PrintPageHandler handler,
  			      optional (unrestricted double or PrintOptions) options);
};

Window implements WindowPrinting;

Bugs

• https://bugzilla.mozilla.org/show_bug.cgi?id=1209273
• https://bugzilla.mozilla.org/show_bug.cgi?id=132035

See Also

CSS Paged Media Module Level 3