embedding/browser/nsIPrintingPrompt.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 /**
   7  * This is the printing prompt interface which can be used without knowlege of a
   8  * parent window. The parentage is hidden by the GetInterface though
   9  * which it is gotten. This interface is identical to nsIPintingPromptService
  10  * but without the parent nsIDOMWindow parameter. See nsIPrintingPromptService
  11  * for all documentation.
  12  */
  13
  14 #include "nsISupports.idl"
  15 #include "nsIWebBrowserPrint.idl"
  16 #include "nsIWebProgressListener.idl"
  17 #include "nsIPrintSettings.idl"
  18 #include "nsIPrintProgressParams.idl"
  19 #include "nsIObserver.idl"
  20
  21 [scriptable, uuid(44E314CA-75B1-4f3d-9553-9B3507912108)]
  22 interface nsIPrintingPrompt : nsISupports
  23 {
  24    /**
  25    *  This service enables embedders to implement their own Print and Progress Dialogs.
  26    *  Each platform has a "base" or "basckstop" implementation of the service. The
  27    *  service is automatically registered at start up.
  28    *
  29    *  Historically, platform toolkits with native dialogs have implemented them in the GFX layer
  30    *  Usually they were displayed when a new DeviceContextSpec specific to that platform
  31    *  was created.
  32    *
  33    *  Windows: The GFX layer no longers supports default toolkit behavior for displaying the
  34    *           native Print Dialog.
  35    *           If an embedder implemented service returns any error code (other than NS_ERROR_ABORT)
  36    *           printing will terminate.
  37    *
  38    *           Returning NS_OK assumes that the PrintSettings object was correctly filled in and
  39    *           if it does not have valid fields for printer name, etc. it may also terminate.
  40    *
  41    *           Defaults for platform service:
  42    *             showPrintDialog       - displays a native dialog
  43    *             showPageSetup         - displays a XUL dialog
  44    *             showProgress          - displays a XUL dialog
  45    *             showPrinterProperties - n/a
  46    *
  47    *           Summary for Windows Embedders:
  48    *             Stated once again: There is no "fallback" native platform support in GFX for the
  49    *             displaying of the native print dialog. The current default implementation for Windows
  50    *             display a native print dialog but a XUL-based progress dialog.
  51    *             If you wish to have a native progress dialog on Windows you will have to create and
  52    *             register your own service.
  53    *
  54    *             Note: The Windows version Mozilla implements this service which is
  55    *                   automatically built and registered for you. You can use it as an example.
  56    *                   It is located at "mozilla/embedding/components/printingui/win". That service
  57    *                   is capable of displaying a native print dialog and a XUL progress dialog.
  58    *
  59    *             To fly your own dialog you may:
  60    *
  61    *              1) Implement this service to display at least the Print Dialog and a Print Progress Dialog
  62    *                 or you may implement just one of the dialogs and pass back NS_ERROR_NOT_IMPLEMENTED
  63    *                 for any of the others.
  64    *
  65    *              2) For the Print Dialog:
  66    *                 You may stub out this service by having all the methods return NS_ERROR_NOT_IMPLEMENTED.
  67    *                 You can then fly you own dialog and then properly fill in the PrintSettings object
  68    *                 before calling nsIWebBrowserPrint's Print method. If you stub out this service
  69    *                 you MUST set "printSilent" to true, if you do not, Printing will terminate and an
  70    *                 error dialog will be displayed.
  71    *
  72    *  Mac: The GFX layer still supports default toolkit behavior for displaying the Print Dialog.
  73    *       If an embedder implemented service returns NS_ERROR_NOT_IMPLEMENTED for "showPrintDialog"
  74    *       The toolkit will display the native print dialog.
  75    *
  76    *       Defaults for platform service:
  77    *       Mac OS9: showPrintDialog       - displays a native dialog
  78    *                showPageSetup         - displays a native dialog
  79    *                showProgress          - displays a XUL dialog
  80    *                showPrinterProperties - n/a
  81    *
  82    *       Mac OSX: showPrintDialog       - displays a native dialog
  83    *                showPageSetup         - displays a native dialog
  84    *                showProgress          - not implemented (provided by OS)
  85    *                showPrinterProperties - n/a
  86    *
  87    *  GTK: There are no native dialog for GTK.
  88    *
  89    *       Defaults for platform service:
  90    *         showPrintDialog       - displays a XUL dialog
  91    *         showPageSetup         - displays a XUL dialog
  92    *         showProgress          - displays a XUL dialog
  93    *         showPrinterProperties - displays a XUL dialog
  94    *
  95    */
  96
  97
  98   /**
  99    *  Show the Print Dialog
 100    *
 101    *  @param webBrowserPrint - represents the document to be printed
 102    *  @param printSettings - PrintSettings for print "job"
 103    *
 104    */
 105   void showPrintDialog(in nsIWebBrowserPrint webBrowserPrint,
 106                        in nsIPrintSettings printSettings);
 107
 108   /**
 109    *  Shows the print progress dialog
 110    *
 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 nsIWebBrowserPrint webBrowserPrint,
 123                     in nsIPrintSettings printSettings,
 124                     in nsIObserver openDialogObserver,
 125                     in boolean isForPrinting,
 126                     out nsIWebProgressListener webProgressListener,
 127                     out nsIPrintProgressParams printProgressParams,
 128                     out boolean notifyOnOpen);
 129
 130   /**
 131    *  Shows the print progress dialog
 132    *
 133    *  @param printSettings - PrintSettings for page setup (required)
 134    *  @param aObs - An observer to know if the contents of the Print Settings
 135    *                object has changed while the dialog is being shown.
 136    *                For example, some platforms may implement an "Apply" button (not required)
 137    */
 138   void showPageSetup(in nsIPrintSettings printSettings, in nsIObserver aObs);
 139
 140   /**
 141    *  Sometimes platforms need to bring up a special properties dialog for showing
 142    *  print specific properties. Although the PrintSettings has a place to set the
 143    *  printer name, here is is an argument to be clear as to what printer is being
 144    *  asked to have the properties set for it. The Printer name in the PS is ignored.
 145    *
 146    *  @param printerName - name of printer (required)
 147    *  @param printSettings - PrintSettings for page setup (required)
 148    */
 149   void showPrinterProperties(in wstring printerName,
 150                              in nsIPrintSettings printSettings);
 151 };