1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/embedding/browser/webBrowser/nsIPrintingPromptService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,165 @@
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 +/* Doc interface here */
1.10 +
1.11 +#include "nsISupports.idl"
1.12 +#include "nsIWebBrowserPrint.idl"
1.13 +#include "nsIWebProgressListener.idl"
1.14 +#include "nsIPrintProgressParams.idl"
1.15 +#include "nsIPrintSettings.idl"
1.16 +#include "nsIObserver.idl"
1.17 +
1.18 +interface nsIDOMWindow;
1.19 +
1.20 +[scriptable, uuid(75D1553D-63BF-4b5d-A8F7-E4E4CAC21BA4)]
1.21 +interface nsIPrintingPromptService : nsISupports
1.22 +{
1.23 + /**
1.24 + * This service enables embedders to implement their own Print and Progress Dialogs.
1.25 + * Each platform has a "base" or "basckstop" implementation of the service. The
1.26 + * service is automatically registered at start up.
1.27 + *
1.28 + * Historically, platform toolkits with native dialogs have implemented them in the GFX layer
1.29 + * Usually they were displayed when a new DeviceContextSpec specific to that platform
1.30 + * was created.
1.31 + *
1.32 + * Windows: The GFX layer no longers supports default toolkit behavior for displaying the
1.33 + * native Print Dialog.
1.34 + * If an embedder implemented service returns any error code (other than NS_ERROR_ABORT)
1.35 + * printing will terminate.
1.36 + *
1.37 + * Returning NS_OK assumes that the PrintSettings object was correctly filled in and
1.38 + * if it does not have valid fields for printer name, etc. it may also terminate.
1.39 + *
1.40 + * Defaults for platform service:
1.41 + * showPrintDialog - displays a native dialog
1.42 + * showPageSetup - displays a XUL dialog
1.43 + * showProgress - displays a XUL dialog
1.44 + * showPrinterProperties - n/a
1.45 + *
1.46 + * Summary for Windows Embedders:
1.47 + * Stated once again: There is no "fallback" native platform support in GFX for the
1.48 + * displaying of the native print dialog. The current default implementation for Windows
1.49 + * display a native print dialog but a XUL-based progress dialog.
1.50 + * If you wish to have a native progress dialog on Windows you will have to create and
1.51 + * register your own service.
1.52 + *
1.53 + * Note: The Windows version Mozilla implements this service which is
1.54 + * automatically built and registered for you. You can use it as an example.
1.55 + * It is located at "mozilla/embedding/components/printingui/src/win". That service
1.56 + * is capable of displaying a native print dialog and a XUL progress dialog.
1.57 + *
1.58 + * To fly your own dialog you may:
1.59 + *
1.60 + * 1) Implement this service to display at least the Print Dialog and a Print Progress Dialog
1.61 + * or you may implement just one of the dialogs and pass back NS_ERROR_NOT_IMPLEMENTED
1.62 + * for any of the others.
1.63 + *
1.64 + * 2) For the Print Dialog:
1.65 + * You may stub out this service by having all the methods return NS_ERROR_NOT_IMPLEMENTED.
1.66 + * You can then fly you own dialog and then properly fill in the PrintSettings object
1.67 + * before calling nsIWebBrowserPrint's Print method. If you stub out this service
1.68 + * you MUST set "printSilent" to true, if you do not, Printing will terminate and an
1.69 + * error dialog will be displayed.
1.70 + *
1.71 + * Mac: The GFX layer still supports default toolkit behavior for displaying the Print Dialog.
1.72 + * If an embedder implemented service returns NS_ERROR_NOT_IMPLEMENTED for "showPrintDialog"
1.73 + * The toolkit will display the native print dialog.
1.74 + *
1.75 + * Defaults for platform service:
1.76 + * Mac OS9: showPrintDialog - displays a native dialog
1.77 + * showPageSetup - displays a native dialog
1.78 + * showProgress - displays a XUL dialog
1.79 + * showPrinterProperties - n/a
1.80 + *
1.81 + * Mac OSX: showPrintDialog - displays a native dialog
1.82 + * showPageSetup - displays a native dialog
1.83 + * showProgress - not implemented (provided by OS)
1.84 + * showPrinterProperties - n/a
1.85 + *
1.86 + * GTK: There are no native dialog for GTK.
1.87 + *
1.88 + * Defaults for platform service:
1.89 + * showPrintDialog - displays a XUL dialog
1.90 + * showPageSetup - displays a XUL dialog
1.91 + * showProgress - displays a XUL dialog
1.92 + * showPrinterProperties - displays a XUL dialog
1.93 + *
1.94 + */
1.95 +
1.96 +
1.97 +
1.98 + /**
1.99 + * Show the Print Dialog
1.100 + *
1.101 + * @param parent - a DOM windows the dialog will be parented to (required)
1.102 + * @param webBrowserPrint - represents the document to be printed (required)
1.103 + * @param printSettings - PrintSettings for print "job" (required)
1.104 + *
1.105 + */
1.106 + void showPrintDialog(in nsIDOMWindow parent,
1.107 + in nsIWebBrowserPrint webBrowserPrint,
1.108 + in nsIPrintSettings printSettings);
1.109 +
1.110 + /**
1.111 + * Shows the print progress dialog
1.112 + *
1.113 + * @param parent - a DOM windows the dialog will be parented to
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 nsIDOMWindow parent,
1.126 + in nsIWebBrowserPrint webBrowserPrint,
1.127 + in nsIPrintSettings printSettings,
1.128 + in nsIObserver openDialogObserver,
1.129 + in boolean isForPrinting,
1.130 + out nsIWebProgressListener webProgressListener,
1.131 + out nsIPrintProgressParams printProgressParams,
1.132 + out boolean notifyOnOpen);
1.133 +
1.134 + /**
1.135 + * Shows the print progress dialog
1.136 + *
1.137 + * @param parent - a DOM windows the dialog will be parented to (required)
1.138 + * @param printSettings - PrintSettings for page setup (required)
1.139 + * @param aObs - An observer to know if the contents of the Print Settings
1.140 + * object has changed while the dialog is being shown.
1.141 + * For example, some platforms may implement an "Apply" button (not required)
1.142 + */
1.143 + void showPageSetup(in nsIDOMWindow parent,
1.144 + in nsIPrintSettings printSettings,
1.145 + in nsIObserver aObs);
1.146 +
1.147 + /**
1.148 + * Sometimes platforms need to bring up a special properties dialog for showing
1.149 + * print specific properties. Although the PrintSettings has a place to set the
1.150 + * printer name, here is is an argument to be clear as to what printer is being
1.151 + * asked to have the properties set for it. The Printer name in the PS is ignored.
1.152 + *
1.153 + * @param parent - a DOM windows the dialog will be parented to (required)
1.154 + * @param printerName - name of printer (required)
1.155 + * @param printSettings - PrintSettings for page setup (required)
1.156 + */
1.157 + void showPrinterProperties(in nsIDOMWindow parent,
1.158 + in wstring printerName,
1.159 + in nsIPrintSettings printSettings);
1.160 +
1.161 +};
1.162 +
1.163 +%{C++
1.164 +// {260FEDC5-524D-4aa6-9A41-E829F4C78B92}
1.165 +#define NS_PRINTINGPROMPTSERVICE_IID \
1.166 + {0x260fedc5, 0x524d, 0x4aa6, { 0x9a, 0x41, 0xe8, 0x29, 0xf4, 0xc7, 0x8b, 0x92}}
1.167 +%}
1.168 +
