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 the default print settings as used for printing.
  34    */
  35   [noscript] readonly attribute nsIPrintSettings defaultPrintSettingsForPrinting;
  36
  37   /**
  38    * Returns a new, unique PrintSettings object each time.
  39    *
  40    * Initializes the newPrintSettings from the unprefixed printer
  41    * (Note: this may not happen if there is an OS specific implementation.)
  42    *
  43    * XXX This should really be a function called `createPrintSettings()`.
  44    */
  45   readonly attribute nsIPrintSettings newPrintSettings;
  46
  47   /**
  48    * The name of the last printer used. Note that this may not be set, or may
  49    * no longer be a valid printer. The caller is responsible for checking and
  50    * falling back to some other printer (such as the system default printer).
  51    *
  52    * XXX: make it [infallible] when AString supports that (bug 1491187).
  53    */
  54   readonly attribute AString lastUsedPrinterName;
  55
  56   /**
  57    * Initializes certain settings from the native printer into the PrintSettings
  58    * if aPrinterName is null then it uses the default printer name if it can
  59    * These settings include, but are not limited to:
  60    *   Page Orientation
  61    *   Page Size
  62    *   Number of Copies
  63    */
  64   void initPrintSettingsFromPrinter(in AString aPrinterName,
  65                                     in nsIPrintSettings aPrintSettings);
  66
  67   /**
  68    * Reads PrintSettings values from Prefs,
  69    * the values to be read are indicated by the "flags" arg.
  70    *
  71    * aPrintSettings should be initialized with the name of a printer. First
  72    * it reads in the PrintSettings from the last print job. Then it uses the
  73    * PrinterName in the PrinterSettings to read any settings that were saved
  74    * just for that printer.
  75    *
  76    * aPS - PrintSettings to have its settings read
  77    * aUsePrinterNamePrefix - indicates whether to use the printer name as a prefix
  78    * aFlags - indicates which prefs to read, see nsIPrintSettings.idl for the
  79    *          const values.
  80    *
  81    * Items not read:
  82    *   startPageRange, endPageRange, scaling, printRange, title
  83    *   docURL, isCancelled,
  84    *   printSilent, shrinkToFit, numCopies,
  85    *   printerName
  86    *
  87    */
  88   void initPrintSettingsFromPrefs(in nsIPrintSettings aPrintSettings, in boolean aUsePrinterNamePrefix, in unsigned long aFlags);
  89
  90   /**
  91    * Writes PrintSettings values to Prefs,
  92    * the values to be written are indicated by the "flags" arg.
  93    *
  94    * If there is no PrinterName in the PrinterSettings
  95    * the values are saved as the "generic" values not associated with any printer.
  96    * If a PrinterName is there, then it saves the items qualified for that Printer
  97    *
  98    * aPS - PrintSettings to have its settings saved
  99    * aUsePrinterNamePrefix - indicates whether to use the printer name as a prefix
 100    * aFlags - indicates which prefs to save, see nsIPrintSettings.idl for the const values.
 101    *
 102    * Items not written:
 103    *   startPageRange, endPageRange, scaling, printRange, title
 104    *   docURL, isCancelled,
 105    *   printSilent, shrinkToFit, numCopies
 106    *
 107    */
 108   void savePrintSettingsToPrefs(in nsIPrintSettings aPrintSettings, in boolean aUsePrinterNamePrefix, in unsigned long aFlags);
 109
 110   /**
 111    * Given some nsIPrintSettings,
 112    * populates a PrintData representing them which can be sent over IPC. Values
 113    * are only ever read from aSettings and aWBP.
 114    *
 115    * @param aSettings
 116    *        An nsIPrintSettings for a print job.
 117    * @param data
 118    *        Pointer to a pre-existing PrintData to populate.
 119    *
 120    * @return nsresult
 121    */
 122   [noscript]
 123   void SerializeToPrintData(in nsIPrintSettings aPrintSettings,
 124                             in PrintDataPtr data);
 125
 126   /**
 127    * This function is the opposite of SerializeToPrintData, in that it takes
 128    * a PrintData, and populates a pre-existing nsIPrintSettings with the data
 129    * from PrintData.
 130    *
 131    * @param PrintData
 132    *        Printing information sent through IPC.
 133    * @param settings
 134    *        A pre-existing nsIPrintSettings to populate with the PrintData.
 135    *
 136    * @return nsresult
 137    */
 138   [noscript]
 139   void DeserializeToPrintSettings(in PrintDataRef data,
 140                                   in nsIPrintSettings aPrintSettings);
 141
 142 };
 143
 144 %{C++
 145 // {841387C8-72E6-484b-9296-BF6EEA80D58A}
 146 #define NS_PRINTSETTINGSSERVICE_IID \
 147  {0x841387c8, 0x72e6, 0x484b, { 0x92, 0x96, 0xbf, 0x6e, 0xea, 0x80, 0xd5, 0x8a}}
 148 %}