nsIPrintingPrompt

This is the printing prompt interface which can be used without knowlege of a parent window. The parentage is hidden by the GetInterface though which it is gotten.
Inherits from: nsISupports Last changed in Gecko 1.7

This interface is identical to nsIPintingPromptService but without the parent nsIDOMWindow parameter. See nsIPrintingPromptService for all documentation.

This service enables embedders to implement their own Print and Progress Dialogs. Each platform has a "base" or "backstop" implementation of the service. The service is automatically registered at start up.

Historically, platform toolkits with native dialogs have implemented them in the GFX layer Usually they were displayed when a new DeviceContextSpec specific to that platform was created.

Windows:

The GFX layer no longer supports default toolkit behavior for displaying the native Print Dialog. If an embedder implemented service returns any error code (other than NS_ERROR_ABORT) printing will terminate.

Returning NS_OK assumes that the PrintSettings object was correctly filled in and if it does not have valid fields for printer name, and so on. it may also terminate.

Defaults for platform service:

Summary for Windows embedders:

  • Stated once again: There is no "fallback" native platform support in GFX for the displaying of the native print dialog. The current default implementation for Windows display a native print dialog but a XUL-based progress dialog. If you wish to have a native progress dialog on Windows you will have to create and register your own service.
  • Note: The Windows version Mozilla implements this service which is automatically built and registered for you. You can use it as an example. It is located at "mozilla/embedding/components/printingui/src/win". That service is capable of displaying a native print dialog and a XUL progress dialog.
  • To fly your own dialog you may:
    1. Implement this service to display at least the Print Dialog and a Print Progress Dialog or you may implement just one of the dialogs and pass back NS_ERROR_NOT_IMPLEMENTED for any of the others.
    2. For the Print Dialog:
      You may stub out this service by having all the methods return NS_ERROR_NOT_IMPLEMENTED. You can then fly you own dialog and then properly fill in the PrintSettings object before calling nsIWebBrowserPrint's Print method. If you stub out this service you MUST set "printSilent" to true, if you do not, Printing will terminate and an error dialog will be displayed.
Mac:

The GFX layer still supports default toolkit behavior for displaying the Print Dialog. If an embedder implemented service returns NS_ERROR_NOT_IMPLEMENTED for "showPrintDialog" The toolkit will display the native print dialog.

Defaults for platform service:

Mac OS X:

GTK:

There are no native dialogs for GTK.

Defaults for platform service:

OS2:

Defaults for platform service:

Method overview

void showPageSetup(in nsIPrintSettings printSettings, in nsIObserver aObs);
void showPrintDialog(in nsIWebBrowserPrint webBrowserPrint, in nsIPrintSettings printSettings);
void showPrinterProperties(in wstring printerName, in nsIPrintSettings printSettings);
void showProgress(in nsIWebBrowserPrint webBrowserPrint, in nsIPrintSettings printSettings, in nsIObserver openDialogObserver, in boolean isForPrinting, out nsIWebProgressListener webProgressListener, out nsIPrintProgressParams printProgressParams, out boolean notifyOnOpen);

Methods

showPageSetup()

Shows the print progress dialog.

void showPageSetup(
  in nsIPrintSettings printSettings,
  in nsIObserver aObs
);
Parameters
printSettings
PrintSettings for page setup.
aObs Optional
An observer to know if the contents of the Print Settings object has changed while the dialog is being shown. For example, some platforms may implement an "Apply" button.

showPrintDialog()

Show the Print Dialog.

void showPrintDialog(
  in nsIWebBrowserPrint webBrowserPrint,
  in nsIPrintSettings printSettings
);
Parameters
webBrowserPrint
Represents the document to be printed.
printSettings
PrintSettings for print "job".

showPrinterProperties()

Sometimes platforms need to bring up a special properties dialog for showing print specific properties. Although the PrintSettings has a place to set the printer name, here is is an argument to be clear as to what printer is being asked to have the properties set for it. The Printer name in the PrintSettings is ignored.

void showPrinterProperties(
  in wstring printerName,
  in nsIPrintSettings printSettings
);
Parameters
printerName
Name of printer.
printSettings
PrintSettings for page setup.

showProgress()

Shows the print progress dialog.

void showProgress(
  in nsIWebBrowserPrint webBrowserPrint,
  in nsIPrintSettings printSettings,
  in nsIObserver openDialogObserver,
  in boolean isForPrinting,
  out nsIWebProgressListener webProgressListener,
  out nsIPrintProgressParams printProgressParams,
  out boolean notifyOnOpen
);
Parameters
webBrowserPrint
Represents the document to be printed.
printSettings
PrintSettings for print "job"
openDialogObserver
An observer that will be notifed when the dialog is opened.
isForPrinting
true - for printing, false for print preview.
webProgressListener
Additional listener can be registered for progress notifications.
printProgressParams
Parameter object for passing progress state.
notifyOnOpen
This indicates that the observer will be notified when the progress dialog has been opened. If false is returned it means the observer (usually the caller) shouldn't wait For Print Preview Progress there is intermediate progress.

Document Tags and Contributors

Tags: 
 Contributors to this page: Sheppy, trevorh
 Last updated by: Sheppy,