1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/embedding/browser/webBrowser/nsIPrintingPrompt.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,151 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +/**
1.10 + * This is the printing prompt interface which can be used without knowlege of a
1.11 + * parent window. The parentage is hidden by the GetInterface though
1.12 + * which it is gotten. This interface is identical to nsIPintingPromptService
1.13 + * but without the parent nsIDOMWindow parameter. See nsIPrintingPromptService
1.14 + * for all documentation.
1.15 + */
1.16 +
1.17 +#include "nsISupports.idl"
1.18 +#include "nsIWebBrowserPrint.idl"
1.19 +#include "nsIWebProgressListener.idl"
1.20 +#include "nsIPrintSettings.idl"
1.21 +#include "nsIPrintProgressParams.idl"
1.22 +#include "nsIObserver.idl"
1.23 +
1.24 +[scriptable, uuid(44E314CA-75B1-4f3d-9553-9B3507912108)]
1.25 +interface nsIPrintingPrompt : nsISupports
1.26 +{
1.27 + /**
1.28 + * This service enables embedders to implement their own Print and Progress Dialogs.
1.29 + * Each platform has a "base" or "basckstop" implementation of the service. The
1.30 + * service is automatically registered at start up.
1.31 + *
1.32 + * Historically, platform toolkits with native dialogs have implemented them in the GFX layer
1.33 + * Usually they were displayed when a new DeviceContextSpec specific to that platform
1.34 + * was created.
1.35 + *
1.36 + * Windows: The GFX layer no longers supports default toolkit behavior for displaying the
1.37 + * native Print Dialog.
1.38 + * If an embedder implemented service returns any error code (other than NS_ERROR_ABORT)
1.39 + * printing will terminate.
1.40 + *
1.41 + * Returning NS_OK assumes that the PrintSettings object was correctly filled in and
1.42 + * if it does not have valid fields for printer name, etc. it may also terminate.
1.43 + *
1.44 + * Defaults for platform service:
1.45 + * showPrintDialog - displays a native dialog
1.46 + * showPageSetup - displays a XUL dialog
1.47 + * showProgress - displays a XUL dialog
1.48 + * showPrinterProperties - n/a
1.49 + *
1.50 + * Summary for Windows Embedders:
1.51 + * Stated once again: There is no "fallback" native platform support in GFX for the
1.52 + * displaying of the native print dialog. The current default implementation for Windows
1.53 + * display a native print dialog but a XUL-based progress dialog.
1.54 + * If you wish to have a native progress dialog on Windows you will have to create and
1.55 + * register your own service.
1.56 + *
1.57 + * Note: The Windows version Mozilla implements this service which is
1.58 + * automatically built and registered for you. You can use it as an example.
1.59 + * It is located at "mozilla/embedding/components/printingui/src/win". That service
1.60 + * is capable of displaying a native print dialog and a XUL progress dialog.
1.61 + *
1.62 + * To fly your own dialog you may:
1.63 + *
1.64 + * 1) Implement this service to display at least the Print Dialog and a Print Progress Dialog
1.65 + * or you may implement just one of the dialogs and pass back NS_ERROR_NOT_IMPLEMENTED
1.66 + * for any of the others.
1.67 + *
1.68 + * 2) For the Print Dialog:
1.69 + * You may stub out this service by having all the methods return NS_ERROR_NOT_IMPLEMENTED.
1.70 + * You can then fly you own dialog and then properly fill in the PrintSettings object
1.71 + * before calling nsIWebBrowserPrint's Print method. If you stub out this service
1.72 + * you MUST set "printSilent" to true, if you do not, Printing will terminate and an
1.73 + * error dialog will be displayed.
1.74 + *
1.75 + * Mac: The GFX layer still supports default toolkit behavior for displaying the Print Dialog.
1.76 + * If an embedder implemented service returns NS_ERROR_NOT_IMPLEMENTED for "showPrintDialog"
1.77 + * The toolkit will display the native print dialog.
1.78 + *
1.79 + * Defaults for platform service:
1.80 + * Mac OS9: showPrintDialog - displays a native dialog
1.81 + * showPageSetup - displays a native dialog
1.82 + * showProgress - displays a XUL dialog
1.83 + * showPrinterProperties - n/a
1.84 + *
1.85 + * Mac OSX: showPrintDialog - displays a native dialog
1.86 + * showPageSetup - displays a native dialog
1.87 + * showProgress - not implemented (provided by OS)
1.88 + * showPrinterProperties - n/a
1.89 + *
1.90 + * GTK: There are no native dialog for GTK.
1.91 + *
1.92 + * Defaults for platform service:
1.93 + * showPrintDialog - displays a XUL dialog
1.94 + * showPageSetup - displays a XUL dialog
1.95 + * showProgress - displays a XUL dialog
1.96 + * showPrinterProperties - displays a XUL dialog
1.97 + *
1.98 + */
1.99 +
1.100 +
1.101 + /**
1.102 + * Show the Print Dialog
1.103 + *
1.104 + * @param webBrowserPrint - represents the document to be printed
1.105 + * @param printSettings - PrintSettings for print "job"
1.106 + *
1.107 + */
1.108 + void showPrintDialog(in nsIWebBrowserPrint webBrowserPrint,
1.109 + in nsIPrintSettings printSettings);
1.110 +
1.111 + /**
1.112 + * Shows the print progress dialog
1.113 + *
1.114 + * @param webBrowserPrint - represents the document to be printed
1.115 + * @param printSettings - PrintSettings for print "job"
1.116 + * @param openDialogObserver - an observer that will be notifed when the dialog is opened
1.117 + * @param isForPrinting - true - for printing, false for print preview
1.118 + * @param webProgressListener - additional listener can be registered for progress notifications
1.119 + * @param printProgressParams - parameter object for passing progress state
1.120 + * @param notifyOnOpen - this indicates that the observer will be notified when the progress
1.121 + * dialog has been opened. If false is returned it means the observer
1.122 + * (usually the caller) shouldn't wait
1.123 + * For Print Preview Progress there is intermediate progress
1.124 + */
1.125 + void showProgress(in nsIWebBrowserPrint webBrowserPrint,
1.126 + in nsIPrintSettings printSettings,
1.127 + in nsIObserver openDialogObserver,
1.128 + in boolean isForPrinting,
1.129 + out nsIWebProgressListener webProgressListener,
1.130 + out nsIPrintProgressParams printProgressParams,
1.131 + out boolean notifyOnOpen);
1.132 +
1.133 + /**
1.134 + * Shows the print progress dialog
1.135 + *
1.136 + * @param printSettings - PrintSettings for page setup (required)
1.137 + * @param aObs - An observer to know if the contents of the Print Settings
1.138 + * object has changed while the dialog is being shown.
1.139 + * For example, some platforms may implement an "Apply" button (not required)
1.140 + */
1.141 + void showPageSetup(in nsIPrintSettings printSettings, in nsIObserver aObs);
1.142 +
1.143 + /**
1.144 + * Sometimes platforms need to bring up a special properties dialog for showing
1.145 + * print specific properties. Although the PrintSettings has a place to set the
1.146 + * printer name, here is is an argument to be clear as to what printer is being
1.147 + * asked to have the properties set for it. The Printer name in the PS is ignored.
1.148 + *
1.149 + * @param printerName - name of printer (required)
1.150 + * @param printSettings - PrintSettings for page setup (required)
1.151 + */
1.152 + void showPrinterProperties(in wstring printerName,
1.153 + in nsIPrintSettings printSettings);
1.154 +};
