widget/nsIPrintSettings.idl

   1 /* -*- Mode: C++; tab-width: 4; 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 #include "nsISupports.idl"
   7
   8 %{ C++
   9 #include "nsMargin.h"
  10 #include "nsTArray.h"
  11
  12 namespace mozilla {
  13 struct PrintSettingsInitializer;
  14 }
  15 %}
  16
  17 /**
  18  * Native types
  19  */
  20 native nsNativeIntMargin(nsIntMargin);
  21 [ref] native nsNativeIntMarginRef(nsIntMargin);
  22
  23 interface nsIPrintSession;
  24 interface nsIOutputStream;
  25
  26 /**
  27  * Simplified graphics interface for JS rendering.
  28  */
  29 [scriptable, builtinclass, uuid(ecc5cbad-57fc-4731-b0bd-09e865bd62ad)]
  30 interface nsIPrintSettings : nsISupports
  31 {
  32   /**
  33    * PrintSettings to be Saved Navigation Constants
  34    */
  35   /* Flag 0x00000001 is unused */
  36   const unsigned long kInitSaveHeaderLeft     = 0x00000002;
  37   const unsigned long kInitSaveHeaderCenter   = 0x00000004;
  38   const unsigned long kInitSaveHeaderRight    = 0x00000008;
  39   const unsigned long kInitSaveFooterLeft     = 0x00000010;
  40   const unsigned long kInitSaveFooterCenter   = 0x00000020;
  41   const unsigned long kInitSaveFooterRight    = 0x00000040;
  42   const unsigned long kInitSaveBGColors       = 0x00000080;
  43   const unsigned long kInitSaveBGImages       = 0x00000100;
  44   const unsigned long kInitSavePaperSize      = 0x00000200;
  45   const unsigned long kInitSaveResolution     = 0x00000400;
  46   const unsigned long kInitSaveDuplex         = 0x00000800;
  47   /* Flag 0x00001000 is unused */
  48   /* Flag 0x00002000 is unused */
  49   const unsigned long kInitSaveUnwriteableMargins = 0x00004000;
  50   const unsigned long kInitSaveEdges          = 0x00008000;
  51
  52   const unsigned long kInitSaveReversed       = 0x00010000;
  53   const unsigned long kInitSaveInColor        = 0x00020000;
  54   const unsigned long kInitSaveOrientation    = 0x00040000;
  55
  56   const unsigned long kInitSavePrinterName    = 0x00100000;
  57   const unsigned long kInitSavePrintToFile    = 0x00200000;
  58   const unsigned long kInitSaveToFileName     = 0x00400000;
  59   const unsigned long kInitSavePageDelay      = 0x00800000;
  60   const unsigned long kInitSaveMargins        = 0x01000000;
  61   const unsigned long kInitSaveNativeData     = 0x02000000;
  62
  63   const unsigned long kInitSaveShrinkToFit    = 0x08000000;
  64   const unsigned long kInitSaveScaling        = 0x10000000;
  65
  66   const unsigned long kInitSaveAll            = 0xFFFFFFFF;
  67
  68   // These settings should be read from global prefs. Other settings should be
  69   // read only from printer-specific prefs.
  70   const unsigned long kGlobalSettings =
  71       kInitSaveHeaderLeft | kInitSaveHeaderCenter | kInitSaveHeaderRight |
  72       kInitSaveFooterLeft | kInitSaveFooterCenter | kInitSaveFooterRight |
  73       kInitSaveEdges | kInitSaveReversed | kInitSaveInColor |
  74       kInitSaveBGColors | kInitSaveBGImages | kInitSaveShrinkToFit;
  75
  76   /* Justification Enums */
  77   const long kJustLeft   = 0;
  78   const long kJustCenter = 1;
  79   const long kJustRight  = 2;
  80
  81   /** Page Size Unit Constants */
  82   const short kPaperSizeInches      = 0;
  83   const short kPaperSizeMillimeters = 1;
  84
  85   /** Orientation Constants */
  86   const short kPortraitOrientation  = 0;
  87   const short kLandscapeOrientation = 1;
  88
  89   /** Output file format */
  90   const short kOutputFormatNative = 0;
  91   const short kOutputFormatPDF    = 2;
  92
  93   /** Output destination */
  94   cenum OutputDestinationType : 8 {
  95     kOutputDestinationPrinter = 0,
  96     kOutputDestinationFile = 1,
  97     kOutputDestinationStream = 2,
  98   };
  99
 100   /**
 101    * Duplex printing options.
 102    *
 103    * Note that other libraries refer to equivalent duplex settings using
 104    * various sets of terminology. This can be confusing and inconsistent both
 105    * with other libraries, and with the behavior that these terms intend to describe.
 106    *
 107    * kDuplexNone is equivalent to Simplex. Thankfully, both of these terms are
 108    * consistent with the behavior that they describe, which is to have single-sided
 109    * printing per sheet.
 110    *
 111    * kDuplexFlipOnLongEdge is equivalent to the following platform-specific constants:
 112    *   CUPS/macOS: NoTumble
 113    *      Windows: DMDUP_VERTICAL
 114    *          GTK: GTK_PRINT_DUPLEX_HORIZONTAL
 115    *
 116    * kDuplexFlipOnShortEdge is equivalent to the following platform-specific constants:
 117    *   CUPS/macOS: Tumble
 118    *      Windows: DMDUP_HORIZONTAL
 119    *          GTK: GTK_PRINT_DUPLEX_VERTICAL
 120    *
 121    *
 122    * Notice that the GTK and Windows constants have opposite meanings for
 123    * VERTICAL and HORIZONTAL.
 124    *
 125    * To make matters more confusing, these platform-specific terms describe different
 126    * behavior (from the user's perspective) depending on whether the sheet is in
 127    * portrait vs. landscape orientation.
 128    *
 129    * For example, the generic term "tumble" describes behavior where a sheet flips over
 130    * a binding on the top edge (like a calendar). This requires that the back side of
 131    * the sheet is printed upside down with respect to the front side of the sheet,
 132    * so that its content appears upright to the reader when they tumble-flip the
 133    * sheet over the top-edge binding.
 134    *
 135    * However, the CUPS/macOS Tumble setting only inverts the back side of the
 136    * sheet in portrait orientation. When you switch to landscape orientation, the
 137    * Tumble setting behaves like a book-like sheet flip, where the front and back
 138    * sides of the sheet are both printed upright with respect to each other.
 139    *
 140    * This is why it is more consistent and more clear to think of these terms
 141    * with regard to sheets being bound on the long edge or the short edge.
 142    *
 143    * kDuplexFlipOnLongEdge  + Portrait  =     book-like flip (front/back same direction)
 144    * kDuplexFlipOnLongEdge  + Landscape = calendar-like flip (front/back inverted)
 145    *
 146    * kDuplexFlipOnShortEdge + Portrait  = calendar-like flip (front/back inverted)
 147    * kDuplexFlipOnShortEdge + Landscape =     book-like flip (front/back same direction)
 148    *
 149    * The long-edge and short-edge terminology unfortunately breaks down when printing
 150    * with square sheet dimensions. Thankfully this edge case (hah) is quite uncommon,
 151    * since most standard printing paper dimensions are not square. Such a paper size
 152    * would even break the uniformly used portrait and landscape terminology.
 153    */
 154   const short kDuplexNone = 0;
 155   const short kDuplexFlipOnLongEdge = 1;
 156   const short kDuplexFlipOnShortEdge = 2;
 157
 158   /**
 159    * Get the page size in twips, considering the
 160    * orientation (portrait or landscape).
 161    */
 162   void GetEffectivePageSize(out double aWidth, out double aHeight);
 163
 164   /**
 165    * Get the printed sheet size in twips, considering both the user-specified
 166    * orientation (portrait or landscape) *as well as* the fact that we might be
 167    * inverting the orientation to account for 2 or 6 pages-per-sheet.
 168    *
 169    * This API will usually behave the same (& return the same thing) as
 170    * GetEffectivePageSize, *except for* when we are printing with 2 or 6
 171    * pages-per-sheet, in which case the return values (aWidth & aHeight) will
 172    * be swapped with respect to what GetEffectivePageSize would return.
 173    *
 174    * Callers should use this method rather than GetEffectivePageSize when they
 175    * really do want the size of the sheet of paper to be printed, rather than
 176    * the possibly-"virtualized"-via-pages-per-sheet page size.
 177    */
 178   [noscript, notxpcom, nostdcall] void GetEffectiveSheetSize(out double aWidth,
 179                                                              out double aHeight);
 180
 181   /**
 182    * Get the orientation of a printed sheet. This is usually the same as the
 183    * 'orientation' attribute (which is the orientation of individual pages),
 184    * except when we're printing with 2 or 6 pages-per-sheet, in which case
 185    * it'll be the opposite value.
 186    *
 187    * Note that this value is not independently settable. Its value is fully
 188    * determined by the 'orientation' and 'numPagesPerSheet' attributes.
 189    */
 190   [noscript, notxpcom, nostdcall] long GetSheetOrientation();
 191
 192   /**
 193    * Convenience getter, which returns true IFF the sheet orientation and the
 194    * page orientation are orthogonal. (In other words, returns true IFF we
 195    * are printing with 2 or 6 pages-per-sheet.)
 196    */
 197   [noscript, notxpcom, nostdcall] bool HasOrthogonalSheetsAndPages();
 198
 199   /**
 200    * Makes a new copy
 201    */
 202   nsIPrintSettings clone();
 203
 204   /**
 205    * Assigns the internal values from the "in" arg to the current object
 206    */
 207   void assign(in nsIPrintSettings aPS);
 208
 209   /**
 210    * Returns true if the settings will result in an equivalent preview and
 211    * therefore print. The printer name is ignored and it allows for a small
 212    * delta in sizes to allow for rounding differences.
 213    */
 214   bool equivalentTo(in nsIPrintSettings aPrintSettings);
 215
 216   /**
 217    * Data Members
 218    */
 219   [noscript] attribute nsIPrintSession printSession; /* We hold a weak reference */
 220
 221   /**
 222    * The edge measurements define the positioning of the headers
 223    * and footers on the page. They're treated as an offset from the edges of
 224    * the page, but are forced to be at least the "unwriteable margin"
 225    * (described below).
 226    */
 227   attribute double  edgeTop;     /*  these are in inches */
 228   attribute double  edgeLeft;
 229   attribute double  edgeBottom;
 230   attribute double  edgeRight;
 231
 232   /**
 233    * The margins define the positioning of the content on the page.
 234    * and footers on the page. They're treated as an offset from the edges of
 235    * the page, but are forced to be at least the "unwriteable margin"
 236    * (described below).
 237    */
 238   attribute double  marginTop;     /*  these are in inches */
 239   attribute double  marginLeft;
 240   attribute double  marginBottom;
 241   attribute double  marginRight;
 242   /**
 243    * The unwriteable margin defines the printable region of the paper.
 244    */
 245   attribute double  unwriteableMarginTop;     /*  these are in inches */
 246   attribute double  unwriteableMarginLeft;
 247   attribute double  unwriteableMarginBottom;
 248   attribute double  unwriteableMarginRight;
 249
 250   attribute double  scaling;      /* values 0.0 - 1.0 */
 251   [infallible] attribute boolean printBGColors; /* Print Background Colors */
 252   [infallible] attribute boolean printBGImages; /* Print Background Images */
 253
 254   /** Whether @page rule margins should be honored or not. */
 255   [infallible] attribute boolean honorPageRuleMargins;
 256
 257   /** Whether to draw guidelines showing the margin settings */
 258   [infallible] attribute boolean showMarginGuides;
 259
 260   /** Whether whether the "print selection" radio button should be enabled
 261    *  in the UI (i.e. whether there is an active selection) */
 262   [infallible] attribute boolean isPrintSelectionRBEnabled;
 263
 264   /** Whether to only print the selected nodes */
 265   [infallible] attribute boolean printSelectionOnly;
 266
 267   attribute AString title;
 268   attribute AString docURL;
 269
 270   attribute AString headerStrLeft;
 271   attribute AString headerStrCenter;
 272   attribute AString headerStrRight;
 273
 274   attribute AString footerStrLeft;
 275   attribute AString footerStrCenter;
 276   attribute AString footerStrRight;
 277
 278   attribute boolean isCancelled;         /* indicates whether the print job has been cancelled */
 279   readonly attribute boolean saveOnCancel;        /* indicates whether the print settings should be saved after a cancel */
 280   attribute boolean printSilent;         /* print without putting up the dialog */
 281   [infallible] attribute boolean shrinkToFit; /* shrinks content to fit on page */
 282
 283   /* Additional XP Related */
 284   attribute AString paperId;       /* identifier of paper (not display name) */
 285   attribute double  paperWidth;    /* width of the paper in inches or mm */
 286   attribute double  paperHeight;   /* height of the paper in inches or mm */
 287   attribute short   paperSizeUnit; /* paper is in inches or mm */
 288
 289   attribute boolean printReversed;
 290   [infallible] attribute boolean printInColor;  /* a false means grayscale */
 291   attribute long    orientation;   /*  see orientation consts */
 292   attribute long    numCopies;
 293
 294   /**
 295    * For numPagesPerSheet, we support these values: 1, 2, 4, 6, 9, 16.
 296    *
 297    * Unsupported values will be treated internally as 1 page per sheet, and
 298    * will trigger assertion failures in debug builds.
 299    */
 300   attribute long    numPagesPerSheet;
 301
 302   /** Output device information */
 303   [infallible] attribute nsIPrintSettings_OutputDestinationType outputDestination;
 304   [infallible] attribute short outputFormat;
 305
 306   attribute AString printerName;          /* for kOutputDestinationPrinter */
 307   attribute AString toFileName;           /* for kOutputDestinationFile */
 308   attribute nsIOutputStream outputStream; /* for kOutputDestinationPrinter */
 309
 310   [infallible] attribute long printPageDelay; /* in milliseconds */
 311
 312   [infallible] attribute long resolution;     /* print resolution (dpi) */
 313
 314   [infallible] attribute long duplex;         /* duplex mode */
 315
 316   /* initialize helpers */
 317   /**
 318    * This attribute tracks whether the PS has been initialized
 319    * from a printer specified by the "printerName" attr.
 320    * If a different name is set into the "printerName"
 321    * attribute than the one it was initialized with the PS
 322    * will then get initialized from that printer.
 323    */
 324   attribute boolean isInitializedFromPrinter;
 325
 326   /**
 327    * This attribute tracks whether the PS has been initialized
 328    * from prefs. If a different name is set into the "printerName"
 329    * attribute than the one it was initialized with the PS
 330    * will then get initialized from prefs again.
 331    */
 332   attribute boolean isInitializedFromPrefs;
 333
 334   /* C++ Helper Functions */
 335   [noscript] void SetMarginInTwips(in nsNativeIntMarginRef aMargin);
 336   [noscript] void SetEdgeInTwips(in nsNativeIntMarginRef aEdge);
 337   [noscript, notxpcom, nostdcall] nsNativeIntMargin GetMarginInTwips();
 338   [noscript, notxpcom, nostdcall] nsNativeIntMargin GetEdgeInTwips();
 339
 340   /**
 341    * Sets/Gets the "unwriteable margin" for the page format.  This defines
 342    * the boundary from which we'll measure the EdgeInTwips and MarginInTwips
 343    * attributes, to place the headers and content, respectively.
 344    *
 345    * Note: Implementations of SetUnwriteableMarginInTwips should handle
 346    * negative margin values by falling back on the system default for
 347    * that margin.
 348    */
 349   [noscript] void SetUnwriteableMarginInTwips(in nsNativeIntMarginRef aEdge);
 350   [noscript, notxpcom, nostdcall] nsNativeIntMargin GetUnwriteableMarginInTwips();
 351
 352   /**
 353    * Get more accurate print ranges from the superior interval
 354    * (startPageRange, endPageRange). The aPages array is populated with a
 355    * list of pairs (start, end), where the endpoints are included. The print
 356    * ranges (start, end), must not overlap and must be in the
 357    * (startPageRange, endPageRange) scope.
 358    *
 359    * If there are no print ranges the aPages array is empty.
 360    */
 361   attribute Array<long> pageRanges;
 362
 363 %{C++
 364   /**
 365    * Get a PrintSettingsInitializer populated with the relevant current settings.
 366    */
 367   virtual mozilla::PrintSettingsInitializer GetSettingsInitializer() = 0;
 368
 369   static bool IsPageSkipped(int32_t aPageNum, const nsTArray<int32_t>& aRanges);
 370 %}
 371 };
 372
 373 %{ C++
 374 already_AddRefed<nsIPrintSettings> CreatePlatformPrintSettings(const mozilla::PrintSettingsInitializer&);
 375 %}