widget/nsIPrintSettingsService.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 /* Interface to the Service for gwetting the Global PrintSettings object
   7    or a unique PrintSettings object
   8 */
   9
  10 #include "nsISupports.idl"
  11
  12 interface nsIPrintSettings;
  13 interface nsIWebBrowserPrint;
  14
  15 %{ C++
  16 namespace mozilla {
  17 namespace embedding {
  18   class PrintData;
  19 }
  20 }
  21 %}
  22
  23 /**
  24  * Native types
  25  */
  26 [ref] native PrintDataRef(const mozilla::embedding::PrintData);
  27 [ptr] native PrintDataPtr(mozilla::embedding::PrintData);
  28
  29 [scriptable, uuid(841387C8-72E6-484b-9296-BF6EEA80D58A)]
  30 interface nsIPrintSettingsService : nsISupports
  31 {
  32   /**
  33    * Returns a "global" PrintSettings object
  34    * Creates a new the first time, if one doesn't exist.
  35    *
  36    * Then returns the same object each time after that.
  37    *
  38    * Initializes the globalPrintSettings from the default printer
  39    */
  40   readonly attribute nsIPrintSettings globalPrintSettings;
  41
  42   /**
  43    * Returns a new, unique PrintSettings object each time.
  44    *
  45    * For example, if each browser was to have its own unique
  46    * PrintSettings, then each browser window would call this to
  47    * create its own unique PrintSettings object.
  48    *
  49    * If each browse window was to use the same PrintSettings object
  50    * then it should use "globalPrintSettings"
  51    *
  52    * Initializes the newPrintSettings from the unprefixed printer
  53    * (Note: this may not happen if there is an OS specific implementation.)
  54    *
  55    */
  56   readonly attribute nsIPrintSettings newPrintSettings;
  57
  58   /**
  59    * The name of the last printer used, or else the system default printer.
  60    */
  61   readonly attribute AString defaultPrinterName;
  62
  63   /**
  64    * Initializes certain settings from the native printer into the PrintSettings
  65    * if aPrinterName is null then it uses the default printer name if it can
  66    * These settings include, but are not limited to:
  67    *   Page Orientation
  68    *   Page Size
  69    *   Number of Copies
  70    */
  71   void initPrintSettingsFromPrinter(in AString aPrinterName,
  72                                     in nsIPrintSettings aPrintSettings);
  73
  74   /**
  75    * Reads PrintSettings values from Prefs,
  76    * the values to be read are indicated by the "flags" arg.
  77    *
  78    * aPrintSettings should be initialized with the name of a printer. First
  79    * it reads in the PrintSettings from the last print job. Then it uses the
  80    * PrinterName in the PrinterSettings to read any settings that were saved
  81    * just for that printer.
  82    *
  83    * aPS - PrintSettings to have its settings read
  84    * aUsePrinterNamePrefix - indicates whether to use the printer name as a prefix
  85    * aFlags - indicates which prefs to read, see nsIPrintSettings.idl for the
  86    *          const values.
  87    *
  88    * Items not read:
  89    *   startPageRange, endPageRange, scaling, printRange, title
  90    *   docURL, howToEnableFrameUI, isCancelled, printFrameTypeUsage
  91    *   printFrameType, printSilent, shrinkToFit, numCopies,
  92    *   printerName
  93    *
  94    */
  95   void initPrintSettingsFromPrefs(in nsIPrintSettings aPrintSettings, in boolean aUsePrinterNamePrefix, in unsigned long aFlags);
  96
  97   /**
  98    * Writes PrintSettings values to Prefs,
  99    * the values to be written are indicated by the "flags" arg.
 100    *
 101    * If there is no PrinterName in the PrinterSettings
 102    * the values are saved as the "generic" values not associated with any printer.
 103    * If a PrinterName is there, then it saves the items qualified for that Printer
 104    *
 105    * aPS - PrintSettings to have its settings saved
 106    * aUsePrinterNamePrefix - indicates whether to use the printer name as a prefix
 107    * aFlags - indicates which prefs to save, see nsIPrintSettings.idl for the const values.
 108    *
 109    * Items not written:
 110    *   startPageRange, endPageRange, scaling, printRange, title
 111    *   docURL, howToEnableFrameUI, isCancelled, printFrameTypeUsage
 112    *   printFrameType, printSilent, shrinkToFit, numCopies
 113    *
 114    */
 115   void savePrintSettingsToPrefs(in nsIPrintSettings aPrintSettings, in boolean aUsePrinterNamePrefix, in unsigned long aFlags);
 116
 117   /**
 118    * Given some nsIPrintSettings and (optionally) an nsIWebBrowserPrint,
 119    * populates a PrintData representing them which can be sent over IPC. Values
 120    * are only ever read from aSettings and aWBP.
 121    *
 122    * @param aSettings
 123    *        An nsIPrintSettings for a print job.
 124    * @param aWBP (optional)
 125    *        The nsIWebBrowserPrint for the print job.
 126    * @param data
 127    *        Pointer to a pre-existing PrintData to populate.
 128    *
 129    * @return nsresult
 130    */
 131   [noscript]
 132   void SerializeToPrintData(in nsIPrintSettings aPrintSettings,
 133                             in nsIWebBrowserPrint aWebBrowserPrint,
 134                             in PrintDataPtr data);
 135
 136   /**
 137    * This function is the opposite of SerializeToPrintData, in that it takes
 138    * a PrintData, and populates a pre-existing nsIPrintSettings with the data
 139    * from PrintData.
 140    *
 141    * @param PrintData
 142    *        Printing information sent through IPC.
 143    * @param settings
 144    *        A pre-existing nsIPrintSettings to populate with the PrintData.
 145    *
 146    * @return nsresult
 147    */
 148   [noscript]
 149   void DeserializeToPrintSettings(in PrintDataRef data,
 150                                   in nsIPrintSettings aPrintSettings);
 151
 152 };
 153
 154 %{C++
 155 // {841387C8-72E6-484b-9296-BF6EEA80D58A}
 156 #define NS_PRINTSETTINGSSERVICE_IID \
 157  {0x841387c8, 0x72e6, 0x484b, { 0x92, 0x96, 0xbf, 0x6e, 0xea, 0x80, 0xd5, 0x8a}}
 158 %}