embedding/browser/nsIPrintingPromptService.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /* Doc interface here */
   7
   8 #include "nsISupports.idl"
   9 #include "nsIWebBrowserPrint.idl"
  10 #include "nsIWebProgressListener.idl"
  11 #include "nsIPrintProgressParams.idl"
  12 #include "nsIPrintSettings.idl"
  13 #include "nsIObserver.idl"
  14
  15 interface nsIDOMWindow;
  16
  17 [scriptable, uuid(75D1553D-63BF-4b5d-A8F7-E4E4CAC21BA4)]
  18 interface nsIPrintingPromptService : nsISupports
  19 {
  20    /**
  21    *  This service enables embedders to implement their own Print and Progress Dialogs.
  22    *  Each platform has a "base" or "basckstop" implementation of the service. The
  23    *  service is automatically registered at start up.
  24    *
  25    *  Historically, platform toolkits with native dialogs have implemented them in the GFX layer
  26    *  Usually they were displayed when a new DeviceContextSpec specific to that platform
  27    *  was created.
  28    *
  29    *  Windows: The GFX layer no longers supports default toolkit behavior for displaying the
  30    *           native Print Dialog.
  31    *           If an embedder implemented service returns any error code (other than NS_ERROR_ABORT)
  32    *           printing will terminate.
  33    *
  34    *           Returning NS_OK assumes that the PrintSettings object was correctly filled in and
  35    *           if it does not have valid fields for printer name, etc. it may also terminate.
  36    *
  37    *           Defaults for platform service:
  38    *             showPrintDialog       - displays a native dialog
  39    *             showPageSetup         - displays a XUL dialog
  40    *             showProgress          - displays a XUL dialog
  41    *             showPrinterProperties - n/a
  42    *
  43    *           Summary for Windows Embedders:
  44    *             Stated once again: There is no "fallback" native platform support in GFX for the
  45    *             displaying of the native print dialog. The current default implementation for Windows
  46    *             display a native print dialog but a XUL-based progress dialog.
  47    *             If you wish to have a native progress dialog on Windows you will have to create and
  48    *             register your own service.
  49    *
  50    *             Note: The Windows version Mozilla implements this service which is
  51    *                   automatically built and registered for you. You can use it as an example.
  52    *                   It is located at "mozilla/embedding/components/printingui/win". That service
  53    *                   is capable of displaying a native print dialog and a XUL progress dialog.
  54    *
  55    *             To fly your own dialog you may:
  56    *
  57    *              1) Implement this service to display at least the Print Dialog and a Print Progress Dialog
  58    *                 or you may implement just one of the dialogs and pass back NS_ERROR_NOT_IMPLEMENTED
  59    *                 for any of the others.
  60    *
  61    *              2) For the Print Dialog:
  62    *                 You may stub out this service by having all the methods return NS_ERROR_NOT_IMPLEMENTED.
  63    *                 You can then fly you own dialog and then properly fill in the PrintSettings object
  64    *                 before calling nsIWebBrowserPrint's Print method. If you stub out this service
  65    *                 you MUST set "printSilent" to true, if you do not, Printing will terminate and an
  66    *                 error dialog will be displayed.
  67    *
  68    *  Mac: The GFX layer still supports default toolkit behavior for displaying the Print Dialog.
  69    *       If an embedder implemented service returns NS_ERROR_NOT_IMPLEMENTED for "showPrintDialog"
  70    *       The toolkit will display the native print dialog.
  71    *
  72    *       Defaults for platform service:
  73    *       Mac OS9: showPrintDialog       - displays a native dialog
  74    *                showPageSetup         - displays a native dialog
  75    *                showProgress          - displays a XUL dialog
  76    *                showPrinterProperties - n/a
  77    *
  78    *       Mac OSX: showPrintDialog       - displays a native dialog
  79    *                showPageSetup         - displays a native dialog
  80    *                showProgress          - not implemented (provided by OS)
  81    *                showPrinterProperties - n/a
  82    *
  83    *  GTK: There are no native dialog for GTK.
  84    *
  85    *       Defaults for platform service:
  86    *         showPrintDialog       - displays a XUL dialog
  87    *         showPageSetup         - displays a XUL dialog
  88    *         showProgress          - displays a XUL dialog
  89    *         showPrinterProperties - displays a XUL dialog
  90    *
  91    */
  92
  93
  94
  95   /**
  96    *  Show the Print Dialog
  97    *
  98    *  @param parent - a DOM windows the dialog will be parented to (required)
  99    *  @param webBrowserPrint - represents the document to be printed (required)
 100    *  @param printSettings - PrintSettings for print "job" (required)
 101    *
 102    */
 103   void showPrintDialog(in nsIDOMWindow parent,
 104                        in nsIWebBrowserPrint webBrowserPrint,
 105                        in nsIPrintSettings printSettings);
 106
 107   /**
 108    *  Shows the print progress dialog
 109    *
 110    *  @param parent - a DOM windows the dialog will be parented to
 111    *  @param webBrowserPrint - represents the document to be printed
 112    *  @param printSettings - PrintSettings for print "job"
 113    *  @param openDialogObserver - an observer that will be notifed when the dialog is opened
 114    *  @param isForPrinting - true - for printing, false for print preview
 115    *  @param webProgressListener - additional listener can be registered for progress notifications
 116    *  @param printProgressParams - parameter object for passing progress state
 117    *  @param notifyOnOpen - this indicates that the observer will be notified when the progress
 118    *                        dialog has been opened. If false is returned it means the observer
 119    *                        (usually the caller) shouldn't wait
 120    *                        For Print Preview Progress there is intermediate progress
 121    */
 122   void showProgress(in nsIDOMWindow parent,
 123                     in nsIWebBrowserPrint webBrowserPrint,
 124                     in nsIPrintSettings printSettings,
 125                     in nsIObserver openDialogObserver,
 126                     in boolean isForPrinting,
 127                     out nsIWebProgressListener webProgressListener,
 128                     out nsIPrintProgressParams printProgressParams,
 129                     out boolean notifyOnOpen);
 130
 131   /**
 132    *  Shows the print progress dialog
 133    *
 134    *  @param parent - a DOM windows the dialog will be parented to (required)
 135    *  @param printSettings - PrintSettings for page setup (required)
 136    *  @param aObs - An observer to know if the contents of the Print Settings
 137    *                object has changed while the dialog is being shown.
 138    *                For example, some platforms may implement an "Apply" button (not required)
 139    */
 140   void showPageSetup(in nsIDOMWindow parent,
 141                      in nsIPrintSettings printSettings,
 142                      in nsIObserver aObs);
 143
 144   /**
 145    *  Sometimes platforms need to bring up a special properties dialog for showing
 146    *  print specific properties. Although the PrintSettings has a place to set the
 147    *  printer name, here is is an argument to be clear as to what printer is being
 148    *  asked to have the properties set for it. The Printer name in the PS is ignored.
 149    *
 150    *  @param parent - a DOM windows the dialog will be parented to (required)
 151    *  @param printerName - name of printer (required)
 152    *  @param printSettings - PrintSettings for page setup (required)
 153    */
 154   void showPrinterProperties(in nsIDOMWindow parent,
 155                              in wstring printerName,
 156                              in nsIPrintSettings printSettings);
 157
 158 };
 159
 160 %{C++
 161 // {260FEDC5-524D-4aa6-9A41-E829F4C78B92}
 162 #define NS_PRINTINGPROMPTSERVICE_IID \
 163  {0x260fedc5, 0x524d, 0x4aa6, { 0x9a, 0x41, 0xe8, 0x29, 0xf4, 0xc7, 0x8b, 0x92}}
 164 %}
 165