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
   9 %{ C++
  10 #include "nsMargin.h"
  11 #include "nsTArray.h"
  12 %}
  13
  14 /**
  15  * Native types
  16  */
  17 native nsNativeIntMargin(nsIntMargin);
  18 [ref] native nsNativeIntMarginRef(nsIntMargin);
  19
  20 interface nsIPrintSession;
  21
  22 /**
  23  * Simplified graphics interface for JS rendering.
  24  */
  25 [scriptable, builtinclass, uuid(ecc5cbad-57fc-4731-b0bd-09e865bd62ad)]
  26 interface nsIPrintSettings : nsISupports
  27 {
  28   /**
  29    * PrintSettings to be Saved Navigation Constants
  30    */
  31   /* Flag 0x00000001 is unused */
  32   const unsigned long kInitSaveHeaderLeft     = 0x00000002;
  33   const unsigned long kInitSaveHeaderCenter   = 0x00000004;
  34   const unsigned long kInitSaveHeaderRight    = 0x00000008;
  35   const unsigned long kInitSaveFooterLeft     = 0x00000010;
  36   const unsigned long kInitSaveFooterCenter   = 0x00000020;
  37   const unsigned long kInitSaveFooterRight    = 0x00000040;
  38   const unsigned long kInitSaveBGColors       = 0x00000080;
  39   const unsigned long kInitSaveBGImages       = 0x00000100;
  40   const unsigned long kInitSavePaperSize      = 0x00000200;
  41   const unsigned long kInitSaveResolution     = 0x00000400;
  42   const unsigned long kInitSaveDuplex         = 0x00000800;
  43   /* Flag 0x00001000 is unused */
  44   /* Flag 0x00002000 is unused */
  45   const unsigned long kInitSaveUnwriteableMargins = 0x00004000;
  46   const unsigned long kInitSaveEdges          = 0x00008000;
  47
  48   const unsigned long kInitSaveReversed       = 0x00010000;
  49   const unsigned long kInitSaveInColor        = 0x00020000;
  50   const unsigned long kInitSaveOrientation    = 0x00040000;
  51
  52   const unsigned long kInitSavePrinterName    = 0x00100000;
  53   const unsigned long kInitSavePrintToFile    = 0x00200000;
  54   const unsigned long kInitSaveToFileName     = 0x00400000;
  55   const unsigned long kInitSavePageDelay      = 0x00800000;
  56   const unsigned long kInitSaveMargins        = 0x01000000;
  57   const unsigned long kInitSaveNativeData     = 0x02000000;
  58
  59   const unsigned long kInitSaveShrinkToFit    = 0x08000000;
  60   const unsigned long kInitSaveScaling        = 0x10000000;
  61
  62   const unsigned long kInitSaveAll            = 0xFFFFFFFF;
  63
  64   /* Justification Enums */
  65   const long kJustLeft   = 0;
  66   const long kJustCenter = 1;
  67   const long kJustRight  = 2;
  68
  69   /**
  70    * Page Size Unit Constants
  71    */
  72   const short kPaperSizeInches      = 0;
  73   const short kPaperSizeMillimeters = 1;
  74
  75   /**
  76    * Orientation Constants
  77    */
  78   const short kPortraitOrientation  = 0;
  79   const short kLandscapeOrientation = 1;
  80
  81   /**
  82    * Output file format
  83    */
  84   const short kOutputFormatNative = 0;
  85   const short kOutputFormatPS     = 1;
  86   const short kOutputFormatPDF    = 2;
  87
  88   /**
  89    * Simplex/Duplex printing options
  90    */
  91   const short kSimplex          = 0;
  92   const short kDuplexHorizontal = 1;
  93   const short kDuplexVertical   = 2;
  94
  95   /**
  96    * Get the page size in twips, considering the
  97    * orientation (portrait or landscape).
  98    */
  99   void GetEffectivePageSize(out double aWidth, out double aHeight);
 100
 101   /**
 102    * Get the printed sheet size in twips, considering both the user-specified
 103    * orientation (portrait or landscape) *as well as* the fact that we might be
 104    * inverting the orientation to account for 2 or 6 pages-per-sheet.
 105    *
 106    * This API will usually behave the same (& return the same thing) as
 107    * GetEffectivePageSize, *except for* when we are printing with 2 or 6
 108    * pages-per-sheet, in which case the return values (aWidth & aHeight) will
 109    * be swapped with respect to what GetEffectivePageSize would return.
 110    *
 111    * Callers should use this method rather than GetEffectivePageSize when they
 112    * really do want the size of the sheet of paper to be printed, rather than
 113    * the possibly-"virtualized"-via-pages-per-sheet page size.
 114    */
 115   [noscript, notxpcom, nostdcall] void GetEffectiveSheetSize(out double aWidth,
 116                                                              out double aHeight);
 117
 118   /**
 119    * Get the orientation of a printed sheet. This is usually the same as the
 120    * 'orientation' attribute (which is the orientation of individual pages),
 121    * except when we're printing with 2 or 6 pages-per-sheet, in which case
 122    * it'll be the opposite value.
 123    *
 124    * Note that this value is not independently settable. Its value is fully
 125    * determined by the 'orientation' and 'numPagesPerSheet' attributes.
 126    */
 127   [noscript, notxpcom, nostdcall] long GetSheetOrientation();
 128
 129   /**
 130    * Convenience getter, which returns true IFF the sheet orientation and the
 131    * page orientation are orthogonal. (In other words, returns true IFF we
 132    * are printing with 2 or 6 pages-per-sheet.)
 133    */
 134   [noscript, notxpcom, nostdcall] bool HasOrthogonalSheetsAndPages();
 135
 136   /**
 137    * Makes a new copy
 138    */
 139   nsIPrintSettings clone();
 140
 141   /**
 142    * Assigns the internal values from the "in" arg to the current object
 143    */
 144   void assign(in nsIPrintSettings aPS);
 145
 146   /**
 147    * Data Members
 148    */
 149   [noscript] attribute nsIPrintSession printSession; /* We hold a weak reference */
 150
 151   /**
 152    * The edge measurements define the positioning of the headers
 153    * and footers on the page. They're treated as an offset from the edges of
 154    * the page, but are forced to be at least the "unwriteable margin"
 155    * (described below).
 156    */
 157   attribute double  edgeTop;     /*  these are in inches */
 158   attribute double  edgeLeft;
 159   attribute double  edgeBottom;
 160   attribute double  edgeRight;
 161
 162   /**
 163    * The margins define the positioning of the content on the page.
 164    * and footers on the page. They're treated as an offset from the edges of
 165    * the page, but are forced to be at least the "unwriteable margin"
 166    * (described below).
 167    */
 168   attribute double  marginTop;     /*  these are in inches */
 169   attribute double  marginLeft;
 170   attribute double  marginBottom;
 171   attribute double  marginRight;
 172   /**
 173    * The unwriteable margin defines the printable region of the paper.
 174    */
 175   attribute double  unwriteableMarginTop;     /*  these are in inches */
 176   attribute double  unwriteableMarginLeft;
 177   attribute double  unwriteableMarginBottom;
 178   attribute double  unwriteableMarginRight;
 179
 180   attribute double  scaling;      /* values 0.0 - 1.0 */
 181   [infallible] attribute boolean printBGColors; /* Print Background Colors */
 182   [infallible] attribute boolean printBGImages; /* Print Background Images */
 183
 184   /** Whether @page rule margins should be honored or not. */
 185   [infallible] attribute boolean honorPageRuleMargins;
 186
 187   /** Whether to draw guidelines showing the margin settings */
 188   [infallible] attribute boolean showMarginGuides;
 189
 190   /** Whether whether the "print selection" radio button should be enabled
 191    *  in the UI (i.e. whether there is an active selection) */
 192   [infallible] attribute boolean isPrintSelectionRBEnabled;
 193
 194   /** Whether to only print the selected nodes */
 195   [infallible] attribute boolean printSelectionOnly;
 196
 197   attribute AString title;
 198   attribute AString docURL;
 199
 200   attribute AString headerStrLeft;
 201   attribute AString headerStrCenter;
 202   attribute AString headerStrRight;
 203
 204   attribute AString footerStrLeft;
 205   attribute AString footerStrCenter;
 206   attribute AString footerStrRight;
 207
 208   attribute boolean isCancelled;         /* indicates whether the print job has been cancelled */
 209   readonly attribute boolean saveOnCancel;        /* indicates whether the print settings should be saved after a cancel */
 210   attribute boolean printSilent;         /* print without putting up the dialog */
 211   attribute boolean shrinkToFit;         /* shrinks content to fit on page      */
 212   attribute boolean showPrintProgress;   /* indicates whether the progress dialog should be shown */
 213
 214   /* Additional XP Related */
 215   attribute AString paperId;       /* identifier of paper (not display name) */
 216   attribute double  paperWidth;    /* width of the paper in inches or mm */
 217   attribute double  paperHeight;   /* height of the paper in inches or mm */
 218   attribute short   paperSizeUnit; /* paper is in inches or mm */
 219
 220   attribute boolean printReversed;
 221   [infallible] attribute boolean printInColor;  /* a false means grayscale */
 222   attribute long    orientation;   /*  see orientation consts */
 223   attribute long    numCopies;
 224
 225   /**
 226    * For numPagesPerSheet, we support these values: 1, 2, 4, 6, 9, 16.
 227    *
 228    * Unsupported values will be treated internally as 1 page per sheet, and
 229    * will trigger assertion failures in debug builds.
 230    */
 231   attribute long    numPagesPerSheet;
 232
 233   attribute AString printerName;   /* name of destination printer */
 234
 235   attribute boolean printToFile;
 236   attribute AString toFileName;
 237   attribute short   outputFormat;
 238
 239   attribute long    printPageDelay; /* in milliseconds */
 240
 241   attribute long    resolution;     /* print resolution (dpi) */
 242
 243   attribute long    duplex;         /* duplex mode */
 244
 245   /* initialize helpers */
 246   /**
 247    * This attribute tracks whether the PS has been initialized
 248    * from a printer specified by the "printerName" attr.
 249    * If a different name is set into the "printerName"
 250    * attribute than the one it was initialized with the PS
 251    * will then get intialized from that printer.
 252    */
 253   attribute boolean isInitializedFromPrinter;
 254
 255   /**
 256    * This attribute tracks whether the PS has been initialized
 257    * from prefs. If a different name is set into the "printerName"
 258    * attribute than the one it was initialized with the PS
 259    * will then get intialized from prefs again.
 260    */
 261   attribute boolean isInitializedFromPrefs;
 262
 263   /* C++ Helper Functions */
 264   [noscript] void SetMarginInTwips(in nsNativeIntMarginRef aMargin);
 265   [noscript] void SetEdgeInTwips(in nsNativeIntMarginRef aEdge);
 266   [noscript, notxpcom, nostdcall] nsNativeIntMargin GetMarginInTwips();
 267   [noscript, notxpcom, nostdcall] nsNativeIntMargin GetEdgeInTwips();
 268
 269   /**
 270    * We call this function so that anything that requires a run of the event loop
 271    * can do so safely. The print dialog runs the event loop but in silent printing
 272    * that doesn't happen.
 273    *
 274    * Either this or ShowPrintDialog (but not both) MUST be called by the print engine
 275    * before printing, otherwise printing can fail on some platforms.
 276    */
 277   [noscript] void SetupSilentPrinting();
 278
 279   /**
 280    * Sets/Gets the "unwriteable margin" for the page format.  This defines
 281    * the boundary from which we'll measure the EdgeInTwips and MarginInTwips
 282    * attributes, to place the headers and content, respectively.
 283    *
 284    * Note: Implementations of SetUnwriteableMarginInTwips should handle
 285    * negative margin values by falling back on the system default for
 286    * that margin.
 287    */
 288   [noscript] void SetUnwriteableMarginInTwips(in nsNativeIntMarginRef aEdge);
 289   [noscript, notxpcom, nostdcall] nsNativeIntMargin GetUnwriteableMarginInTwips();
 290
 291   /**
 292    * Get more accurate print ranges from the superior interval
 293    * (startPageRange, endPageRange). The aPages array is populated with a
 294    * list of pairs (start, end), where the endpoints are included. The print
 295    * ranges (start, end), must not overlap and must be in the
 296    * (startPageRange, endPageRange) scope.
 297    *
 298    * If there are no print ranges the aPages array is empty.
 299    */
 300   attribute Array<long> pageRanges;
 301
 302 %{C++
 303   static bool IsPageSkipped(int32_t aPageNum, const nsTArray<int32_t>& aRanges);
 304 %}
 305 };
 306
 307 %{ C++
 308 namespace mozilla {
 309 struct PrintSettingsInitializer;
 310 }
 311
 312 already_AddRefed<nsIPrintSettings> CreatePlatformPrintSettings(const mozilla::PrintSettingsInitializer&);
 313 %}