webOS Printing

In HP/Palm's webOS 3.0, applications have two options for printing:

  1. Print Dialog -- Enyo apps can launch this type of Popup control. The Print Dialog lets users choose or add a printer, select print options, and print existing image files or WebKit-rendered content. The Print Dialog calls the Print Manager service -- com.palm.printmgr -- for all printer interaction.

  2. Print Manager APIs -- Through Enyo service wrapper calls, apps can invoke Print Manager APIs directly to customize printing and rendering to meet their specific needs.

It is strongly recommended that apps use the first option. The vast majority of apps should be able to rely exclusively on the Print Dialog to meet all their printing needs, including WebKit-rendered content.

Printing Images and WebKit-Rendered Content

The Print Manager only prints page images in JPEG format. When images are not existing device files, WebKit is used to render the app-specific content (HTML/text) into page images suitable for printing. With the Print Dialog, apps can move content they want rendered into a browser frame (visible or not) and pass the frame's name as a parameter to the Print Dialog. The Print Dialog then, on the app's behalf, renders that frame's content into images suitable for printing. Apps also have the option to specifiy a callback function they want the Print Dialog to invoke for custom rendering. When the user selects "print", the Print Dialog calls the Print Manager service to initiate a print job with the selected options and files.

Printer Discovery

Printers are either automatically discovered using Zeroconf (Zero configuration networking), or manually added based on IPv4 address. Available printers are determined by a user's SSID (Service Set IDentifier) -- an access point identifying a specific 802.11 wireless LAN. Zeroconf does not detect printers attached to other access points. Apple's Zeroconf version is called Bonjour, so printers may advertise they support that. For most users, this should be sufficient to discover available printers. However, if the access point is configured to block multi-cast (which Zeroconf needs), or the printer has Zeroconf turned off, it may be necessary to add the printer manually.

Margins and Insets

If not operating in borderless mode, margins determine how close to the paper's edges the printer can print. The printer specifies the page margins which apps cannot change. Margins are denoted in inches for the top, left, right, and bottom.

Applications can, however, specify the margins for the printed output; these are referred to as insets (to differentiate them from printer margins). Like margins, insets are specified from the edge of the page. They must be larger than or equal to the printer margins.
Also like margins, insets are denoted in inches for the top, left, right, and bottom.

If the printer supports borderless mode, and the app specifies it, insets are not supported. Specifying both insets and borderless mode results in an error.

Note: The Print Dialog's margin object can be used to define insets. In the Print Manager API calls, inset properties contain the text "Inset", i.e., rightInset, leftInset, etc.

Target Audience

This document assumes the reader has some knowledge, or experience coding, with HP/Palm's new Enyo JavaScript framework. Specifically, you are familiar with how to use an Enyo Popup control (Print Dialog) from within the Enyo framework. See HP/Palm's Enyo documentation for more information.

Note: Currently, only networked HP printers are supported.

Using the Print Dialog

Figure 1: Example Print Dialog for manually added printer

The Print Dialog, in the Enyo JavaScript framework, is a type of pop-up (kind: enyo.Popup), 351px wide by 372px high, that lets the user choose a printer, select print options and print a set of images or rendered documents.

Your Enyo app has three options for printing content with the Print Dialog:

  1. Print existing JPEG images -- Use the Print Dialog's imagesPath and imagesToPrint parameters.

  2. Print frame content -- Use the frameToPrint parameter.

  3. Print with a custom rendering function -- Use the onRenderDocument parameter.

One of these options must be specified, and only one can be used.

To include the Print Dialog in your Enyo app:

Since the Print Dialog is a library, your app needs to include a "$enyo-lib/printdialog/" entry in your call to enyo.depends().

For example: 

 enyo.depends(
    "source/FeedReader.js",
    "source/Search.js",
    "css/FeedReader.css",
   "$enyo-lib/printdialog/" 
 );

You can set the following properties to customize the Print Dialog when it appears in your app:

Parameter Required Type Description
pageRange No object The minimum and maximum number of pages that can be printed.
copiesRange No object The minimum (1 or more) and maximum (20 or less) number of copies that can be printed.
margin No object Default page margins for the print job in inches (i.e., {top: 0.5, left: 0.5, right: 0.5, bottom: 0.5}). These are what was referred to as "insets" at the top. By default, images are printed borderless with no margins while documents default to 0.5 inch for all.
duplexOption No boolean User can select 2-sided printing flag.
mediaSizeOption No boolean User can select media size flag.
mediaTypeOption No boolean User can select media type flag.
colorOption No boolean User can select color flag.
qualityOption No boolean User can select print quality flag.
imagesToPrint No string array

JPEG images to print. Besides the image file name (i.e., "image.jpg"), you can also include a full or partial path name. The imagesPath value is prepended to each string in this array.

Either this, frameToPrint or onRenderDocument is required. Only one can be used.

imagesPath No string Path to images. This is prepended to the imagesToPath strings. Note that it could be either a full or partial path. Defaults to the empty string if not included.
frameToPrint No object Inline object, see two fields below. Either this, imagesToPrint or onRenderDocument is required. Only one can be used.
frameToPrint.name No string Name of frame whose content you want to render and print. If empty string (""), the main frame is used.
frameToPrint.landscape No boolean Print frame content in landscape or portrait flag.
appName No string Calling app's name.
onRenderDocument No string

Rendering function for WebKit content.

Either this, frameToPrint, or imagesToPrint is required. Only one can be used.

Examples

Printing Demo Sample App

For a complete app example that uses the Print Dialog, see the com.palm.app.printdemo sample application included with the webOS 3.0 SDK.

Standard usage with no rendering 

 {name: "printDialog", kind: "PrintDialog",
         pageRange  : {min: 1, max: 20},
         copiesRange: {min: 1, max: 10},
         margin : {top: 0.5, left: 0.5, right: 0.5, bottom: 0.5},
         mediaSizeOption: true,
         colorOption: true,
         imagePath: "/media/internal/",
         imagesToPrint: ["image1.jpeg", "image2.jpeg", "image3.jpeg"],
         appName: "Photos"} 
 
 this.$.printDialog.openAtCenter();  // Standard enyo.Popup method

Printing frame content 

 {name: "printDialog", kind: "PrintDialog",
         duplexOption: true,
         colorOption: true,
         frameToPrint: {name:"", landscape:false},
         appName: "TestApp"}

To selectively print frame content:

If you are interested in printing some frame elements, but not others, use a CSS stylesheet for printing.

  1. Include a reference to the stylesheet (does not have to be named "PrintMedia.css") with a media="print" attribute in your depends.js file: 
 enyo.depends(
   "$enyo-lib/printdialog/",
   "source/PrintDemo.js"
 );
 document.write('<link href="PrintMedia.css" media="print" rel="stylesheet" type="text/css"/>');
  1. In your stylesheet, indicate the elements you do not want printed. For example: 
 #navigation, #advertising  { display: none; }

For more information on CSS formatting, see CSS For Print-Friendly Pages, or numerous other articles on the Internet.

Printing with custom rendering

To print a custom rendered document, use the onRenderDocument event to render the document and add the rendered document to the print job.

Using PrintDialog to print a web page from the browser: 

 {name: "printDialog", kind: "PrintDialog",
         copiesRange: {min: 1, max: 10},
         pageRange: {min: 1, max: 20},
         duplexOption: true,
         mediaSizeOption : true,
         mediaTypeOption : true,
         colorOption: true,
         qualityOption: true,
         onRenderDocument: "renderWebPage",
         appName: "Browser"}

 this.$.printDialog.openAtCenter();

 renderWebPage: function(inSender, inJobID, inPrintParams) {
         this.$.view.callBrowserAdapter("printFrame",
         ["",         // Frame name, uses "_self" if empty.
         inJobID,
         inPrintParams.width,
         inPrintParams.height,
         inPrintParams.pixelUnits,  // Same as DPI
         false, // print in portrait
         inPrintParams.renderInReverseOrder]);
 }

The Print Dialog app handles completion of the job after the rendered pages have been added.