embedding/browser/webBrowser/nsIPrintingPromptService.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) 2001
  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 /* Doc interface here */
  39
  40 #include "nsISupports.idl"
  41 #include "nsIWebBrowserPrint.idl"
  42 #include "nsIWebProgressListener.idl"
  43 #include "nsIPrintProgressParams.idl"
  44 #include "nsIPrintSettings.idl"
  45 #include "nsIObserver.idl"
  46
  47 interface nsIDOMWindow;
  48
  49 [scriptable, uuid(75D1553D-63BF-4b5d-A8F7-E4E4CAC21BA4)]
  50 interface nsIPrintingPromptService : nsISupports
  51 {
  52    /**
  53    *  This service enables embedders to implement their own Print and Progress Dialogs.
  54    *  Each platform has a "base" or "basckstop" implementation of the service. The
  55    *  service is automatically registered at start up.
  56    *
  57    *  Historically, platform toolkits with native dialogs have implemented them in the GFX layer
  58    *  Usually they were displayed when a new DeviceContextSpec specific to that platform
  59    *  was created.
  60    *
  61    *  Windows: The GFX layer no longers supports default toolkit behavior for displaying the
  62    *           native Print Dialog.
  63    *           If an embedder implemented service returns any error code (other than NS_ERROR_ABORT)
  64    *           printing will terminate.
  65    *
  66    *           Returning NS_OK assumes that the PrintSettings object was correctly filled in and
  67    *           if it does not have valid fields for printer name, etc. it may also terminate.
  68    *
  69    *           Defaults for platform service:
  70    *             showPrintDialog       - displays a native dialog
  71    *             showPageSetup         - displays a XUL dialog
  72    *             showProgress          - displays a XUL dialog
  73    *             showPrinterProperties - n/a
  74    *
  75    *           Summary for Windows Embedders:
  76    *             Stated once again: There is no "fallback" native platform support in GFX for the
  77    *             displaying of the native print dialog. The current default implementation for Windows
  78    *             display a native print dialog but a XUL-based progress dialog.
  79    *             If you wish to have a native progress dialog on Windows you will have to create and
  80    *             register your own service.
  81    *
  82    *             Note: The Windows version Mozilla implements this service which is
  83    *                   automatically built and registered for you. You can use it as an example.
  84    *                   It is located at "mozilla/embedding/components/printingui/src/win". That service
  85    *                   is capable of displaying a native print dialog and a XUL progress dialog.
  86    *
  87    *             To fly your own dialog you may:
  88    *
  89    *              1) Implement this service to display at least the Print Dialog and a Print Progress Dialog
  90    *                 or you may implement just one of the dialogs and pass back NS_ERROR_NOT_IMPLEMENTED
  91    *                 for any of the others.
  92    *
  93    *              2) For the Print Dialog:
  94    *                 You may stub out this service by having all the methods return NS_ERROR_NOT_IMPLEMENTED.
  95    *                 You can then fly you own dialog and then properly fill in the PrintSettings object
  96    *                 before calling nsIWebBrowserPrint's Print method. If you stub out this service
  97    *                 you MUST set "printSilent" to true, if you do not, Printing will terminate and an
  98    *                 error dialog will be displayed.
  99    *
 100    *  Mac: The GFX layer still supports default toolkit behavior for displaying the Print Dialog.
 101    *       If an embedder implemented service returns NS_ERROR_NOT_IMPLEMENTED for "showPrintDialog"
 102    *       The toolkit will display the native print dialog.
 103    *
 104    *       Defaults for platform service:
 105    *       Mac OS9: showPrintDialog       - displays a native dialog
 106    *                showPageSetup         - displays a native dialog
 107    *                showProgress          - displays a XUL dialog
 108    *                showPrinterProperties - n/a
 109    *
 110    *       Mac OSX: showPrintDialog       - displays a native dialog
 111    *                showPageSetup         - displays a native dialog
 112    *                showProgress          - not implemented (provided by OS)
 113    *                showPrinterProperties - n/a
 114    *
 115    *  GTK: There are no native dialog for GTK.
 116    *
 117    *       Defaults for platform service:
 118    *         showPrintDialog       - displays a XUL dialog
 119    *         showPageSetup         - displays a XUL dialog
 120    *         showProgress          - displays a XUL dialog
 121    *         showPrinterProperties - displays a XUL dialog
 122    *
 123    *  OS2:
 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 native dialog
 130    *
 131    *
 132    */
 133
 134
 135
 136   /**
 137    *  Show the Print Dialog
 138    *
 139    *  @param parent - a DOM windows the dialog will be parented to (required)
 140    *  @param webBrowserPrint - represents the document to be printed (required)
 141    *  @param printSettings - PrintSettings for print "job" (required)
 142    *
 143    */
 144   void showPrintDialog(in nsIDOMWindow parent,
 145                        in nsIWebBrowserPrint webBrowserPrint,
 146                        in nsIPrintSettings printSettings);
 147
 148   /**
 149    *  Shows the print progress dialog
 150    *
 151    *  @param parent - a DOM windows the dialog will be parented to
 152    *  @param webBrowserPrint - represents the document to be printed
 153    *  @param printSettings - PrintSettings for print "job"
 154    *  @param openDialogObserver - an observer that will be notifed when the dialog is opened
 155    *  @param isForPrinting - true - for printing, false for print preview
 156    *  @param webProgressListener - additional listener can be registered for progress notifications
 157    *  @param printProgressParams - parameter object for passing progress state
 158    *  @param notifyOnOpen - this indicates that the observer will be notified when the progress
 159    *                        dialog has been opened. If false is returned it means the observer
 160    *                        (usually the caller) shouldn't wait
 161    *                        For Print Preview Progress there is intermediate progress
 162    */
 163   void showProgress(in nsIDOMWindow parent,
 164                     in nsIWebBrowserPrint webBrowserPrint,
 165                     in nsIPrintSettings printSettings,
 166                     in nsIObserver openDialogObserver,
 167                     in boolean isForPrinting,
 168                     out nsIWebProgressListener webProgressListener,
 169                     out nsIPrintProgressParams printProgressParams,
 170                     out boolean notifyOnOpen);
 171
 172   /**
 173    *  Shows the print progress dialog
 174    *
 175    *  @param parent - a DOM windows the dialog will be parented to (required)
 176    *  @param printSettings - PrintSettings for page setup (required)
 177    *  @param aObs - An observer to know if the contents of the Print Settings
 178    *                object has changed while the dialog is being shown.
 179    *                For example, some platforms may implement an "Apply" button (not required)
 180    */
 181   void showPageSetup(in nsIDOMWindow parent,
 182                      in nsIPrintSettings printSettings,
 183                      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 parent - a DOM windows the dialog will be parented to (required)
 192    *  @param printerName - name of printer (required)
 193    *  @param printSettings - PrintSettings for page setup (required)
 194    */
 195   void showPrinterProperties(in nsIDOMWindow parent,
 196                              in wstring printerName,
 197                              in nsIPrintSettings printSettings);
 198
 199 };
 200
 201 %{C++
 202 // {260FEDC5-524D-4aa6-9A41-E829F4C78B92}
 203 #define NS_PRINTINGPROMPTSERVICE_IID \
 204  {0x260fedc5, 0x524d, 0x4aa6, { 0x9a, 0x41, 0xe8, 0x29, 0xf4, 0xc7, 0x8b, 0x92}}
 205 %}
 206