embedding/browser/webBrowser/nsIPrintingPrompt.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 /**
  39  * @status UNDER_REVIEW
  40  */
  41
  42 /**
  43  * This is the printing prompt interface which can be used without knowlege of a
  44  * parent window. The parentage is hidden by the GetInterface though
  45  * which it is gotten. This interface is identical to nsIPintingPromptService
  46  * but without the parent nsIDOMWindow parameter. See nsIPrintingPromptService
  47  * for all documentation.
  48  */
  49
  50 #include "nsISupports.idl"
  51 #include "nsIWebBrowserPrint.idl"
  52 #include "nsIWebProgressListener.idl"
  53 #include "nsIPrintSettings.idl"
  54 #include "nsIPrintProgressParams.idl"
  55 #include "nsIObserver.idl"
  56
  57 [scriptable, uuid(44E314CA-75B1-4f3d-9553-9B3507912108)]
  58 interface nsIPrintingPrompt : nsISupports
  59 {
  60    /**
  61    *  This service enables embedders to implement their own Print and Progress Dialogs.
  62    *  Each platform has a "base" or "basckstop" implementation of the service. The
  63    *  service is automatically registered at start up.
  64    *
  65    *  Historically, platform toolkits with native dialogs have implemented them in the GFX layer
  66    *  Usually they were displayed when a new DeviceContextSpec specific to that platform
  67    *  was created.
  68    *
  69    *  Windows: The GFX layer no longers supports default toolkit behavior for displaying the
  70    *           native Print Dialog.
  71    *           If an embedder implemented service returns any error code (other than NS_ERROR_ABORT)
  72    *           printing will terminate.
  73    *
  74    *           Returning NS_OK assumes that the PrintSettings object was correctly filled in and
  75    *           if it does not have valid fields for printer name, etc. it may also terminate.
  76    *
  77    *           Defaults for platform service:
  78    *             showPrintDialog       - displays a native dialog
  79    *             showPageSetup         - displays a XUL dialog
  80    *             showProgress          - displays a XUL dialog
  81    *             showPrinterProperties - n/a
  82    *
  83    *           Summary for Windows Embedders:
  84    *             Stated once again: There is no "fallback" native platform support in GFX for the
  85    *             displaying of the native print dialog. The current default implementation for Windows
  86    *             display a native print dialog but a XUL-based progress dialog.
  87    *             If you wish to have a native progress dialog on Windows you will have to create and
  88    *             register your own service.
  89    *
  90    *             Note: The Windows version Mozilla implements this service which is
  91    *                   automatically built and registered for you. You can use it as an example.
  92    *                   It is located at "mozilla/embedding/components/printingui/src/win". That service
  93    *                   is capable of displaying a native print dialog and a XUL progress dialog.
  94    *
  95    *             To fly your own dialog you may:
  96    *
  97    *              1) Implement this service to display at least the Print Dialog and a Print Progress Dialog
  98    *                 or you may implement just one of the dialogs and pass back NS_ERROR_NOT_IMPLEMENTED
  99    *                 for any of the others.
 100    *
 101    *              2) For the Print Dialog:
 102    *                 You may stub out this service by having all the methods return NS_ERROR_NOT_IMPLEMENTED.
 103    *                 You can then fly you own dialog and then properly fill in the PrintSettings object
 104    *                 before calling nsIWebBrowserPrint's Print method. If you stub out this service
 105    *                 you MUST set "printSilent" to true, if you do not, Printing will terminate and an
 106    *                 error dialog will be displayed.
 107    *
 108    *  Mac: The GFX layer still supports default toolkit behavior for displaying the Print Dialog.
 109    *       If an embedder implemented service returns NS_ERROR_NOT_IMPLEMENTED for "showPrintDialog"
 110    *       The toolkit will display the native print dialog.
 111    *
 112    *       Defaults for platform service:
 113    *       Mac OS9: showPrintDialog       - displays a native dialog
 114    *                showPageSetup         - displays a native dialog
 115    *                showProgress          - displays a XUL dialog
 116    *                showPrinterProperties - n/a
 117    *
 118    *       Mac OSX: showPrintDialog       - displays a native dialog
 119    *                showPageSetup         - displays a native dialog
 120    *                showProgress          - not implemented (provided by OS)
 121    *                showPrinterProperties - n/a
 122    *
 123    *  GTK: There are no native dialog for GTK.
 124    *
 125    *       Defaults for platform service:
 126    *         showPrintDialog       - displays a XUL dialog
 127    *         showPageSetup         - displays a XUL dialog
 128    *         showProgress          - displays a XUL dialog
 129    *         showPrinterProperties - displays a XUL dialog
 130    *
 131    *  OS2:
 132    *
 133    *       Defaults for platform service:
 134    *         showPrintDialog       - displays a XUL dialog
 135    *         showPageSetup         - displays a XUL dialog
 136    *         showProgress          - displays a XUL dialog
 137    *         showPrinterProperties - displays a native dialog
 138    *
 139    *
 140    */
 141
 142
 143   /**
 144    *  Show the Print Dialog
 145    *
 146    *  @param webBrowserPrint - represents the document to be printed
 147    *  @param printSettings - PrintSettings for print "job"
 148    *
 149    */
 150   void showPrintDialog(in nsIWebBrowserPrint webBrowserPrint,
 151                        in nsIPrintSettings printSettings);
 152
 153   /**
 154    *  Shows the print progress dialog
 155    *
 156    *  @param webBrowserPrint - represents the document to be printed
 157    *  @param printSettings - PrintSettings for print "job"
 158    *  @param openDialogObserver - an observer that will be notifed when the dialog is opened
 159    *  @param isForPrinting - true - for printing, false for print preview
 160    *  @param webProgressListener - additional listener can be registered for progress notifications
 161    *  @param printProgressParams - parameter object for passing progress state
 162    *  @param notifyOnOpen - this indicates that the observer will be notified when the progress
 163    *                        dialog has been opened. If false is returned it means the observer
 164    *                        (usually the caller) shouldn't wait
 165    *                        For Print Preview Progress there is intermediate progress
 166    */
 167   void showProgress(in nsIWebBrowserPrint webBrowserPrint,
 168                     in nsIPrintSettings printSettings,
 169                     in nsIObserver openDialogObserver,
 170                     in boolean isForPrinting,
 171                     out nsIWebProgressListener webProgressListener,
 172                     out nsIPrintProgressParams printProgressParams,
 173                     out boolean notifyOnOpen);
 174
 175   /**
 176    *  Shows the print progress dialog
 177    *
 178    *  @param printSettings - PrintSettings for page setup (required)
 179    *  @param aObs - An observer to know if the contents of the Print Settings
 180    *                object has changed while the dialog is being shown.
 181    *                For example, some platforms may implement an "Apply" button (not required)
 182    */
 183   void showPageSetup(in nsIPrintSettings printSettings, in nsIObserver aObs);
 184
 185   /**
 186    *  Sometimes platforms need to bring up a special properties dialog for showing
 187    *  print specific properties. Although the PrintSettings has a place to set the
 188    *  printer name, here is is an argument to be clear as to what printer is being
 189    *  asked to have the properties set for it. The Printer name in the PS is ignored.
 190    *
 191    *  @param printerName - name of printer (required)
 192    *  @param printSettings - PrintSettings for page setup (required)
 193    */
 194   void showPrinterProperties(in wstring printerName,
 195                              in nsIPrintSettings printSettings);
 196 };