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