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