/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsIPrinter.idl"
#include "nsIPrintSettings.idl"

[scriptable, uuid(5e738fff-404c-4c94-9189-e8f2cce93e94)]
interface nsIPrinterList : nsISupports
{
  /**
   * Initializes certain settings from the native printer into the PrintSettings
   * These settings include, but are not limited to:
   *   Page Orientation
   *   Page Size
   *   Number of Copies
   */
  void initPrintSettingsFromPrinter(in AString aPrinterName,
                                    in nsIPrintSettings aPrintSettings);

  /**
   * The system default printer name. This is not necessarily gecko's
   * default printer; see nsIPrintSettingsService.lastUsedPrinterName
   * for that.
   */
  readonly attribute AString systemDefaultPrinterName;

  /**
   * Returns a promise that resolves to the printer of a given name, or is
   * rejected if there is no such printer.
   */
  [implicit_jscontext] Promise getPrinterByName(in AString aPrinterName);

  /**
   * Returns a promise that resolves to the printer of a given system name, or
   * is rejected if there is no such printer.
   * This may be more efficient than using getNamedPrinter, but requires the
   * caller to know the system name of the printer they want to find.
   */
  [implicit_jscontext] Promise getPrinterBySystemName(in AString aPrinterName);

  /**
   * Returns a promise that resolves to the printer of the given name, or
   * the default system printer, or is rejected if there are no printers
   * available.
   */
  [implicit_jscontext] Promise getNamedOrDefaultPrinter(in AString aPrinterName);

  /**
   * Returns a promise that resolves to an array of printers.
   */
  [implicit_jscontext] readonly attribute Promise printers;

  /**
   * Returns a Promise that resolves to an array of nsIPaper instances
   * for common paper sizes suitable to be supported for Save to PDF.
   */
  [implicit_jscontext] readonly attribute Promise fallbackPaperList;
};