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   [ref] native nsNativeIntMarginRef(nsIntMargin);
  18   [ref] native IntegerArray(nsTArray<int32_t>);
  19
  20 interface nsIPrintSession;
  21
  22 /**
  23  * Simplified graphics interface for JS rendering.
  24  */
  25 [scriptable, uuid(1bcfc611-8941-4c39-9e06-7116e564a1ce)]
  26
  27 interface nsIPrintSettings : nsISupports
  28 {
  29   /**
  30    * PrintSettings to be Saved Navigation Constants
  31    */
  32   const unsigned long kInitSaveOddEvenPages   = 0x00000001;
  33   const unsigned long kInitSaveHeaderLeft     = 0x00000002;
  34   const unsigned long kInitSaveHeaderCenter   = 0x00000004;
  35   const unsigned long kInitSaveHeaderRight    = 0x00000008;
  36   const unsigned long kInitSaveFooterLeft     = 0x00000010;
  37   const unsigned long kInitSaveFooterCenter   = 0x00000020;
  38   const unsigned long kInitSaveFooterRight    = 0x00000040;
  39   const unsigned long kInitSaveBGColors       = 0x00000080;
  40   const unsigned long kInitSaveBGImages       = 0x00000100;
  41   const unsigned long kInitSavePaperSize      = 0x00000200;
  42   const unsigned long kInitSaveResolution     = 0x00000400;
  43   const unsigned long kInitSaveDuplex         = 0x00000800;
  44   /* Flag 0x00001000 is unused */
  45   const unsigned long kInitSavePaperData      = 0x00002000;
  46   const unsigned long kInitSaveUnwriteableMargins = 0x00004000;
  47   const unsigned long kInitSaveEdges          = 0x00008000;
  48
  49   const unsigned long kInitSaveReversed       = 0x00010000;
  50   const unsigned long kInitSaveInColor        = 0x00020000;
  51   const unsigned long kInitSaveOrientation    = 0x00040000;
  52   const unsigned long kInitSavePrintCommand   = 0x00080000;
  53   const unsigned long kInitSavePrinterName    = 0x00100000;
  54   const unsigned long kInitSavePrintToFile    = 0x00200000;
  55   const unsigned long kInitSaveToFileName     = 0x00400000;
  56   const unsigned long kInitSavePageDelay      = 0x00800000;
  57   const unsigned long kInitSaveMargins        = 0x01000000;
  58   const unsigned long kInitSaveNativeData     = 0x02000000;
  59   const unsigned long kInitSavePlexName       = 0x04000000;
  60   const unsigned long kInitSaveShrinkToFit    = 0x08000000;
  61   const unsigned long kInitSaveScaling        = 0x10000000;
  62   const unsigned long kInitSaveColorspace     = 0x20000000;
  63   const unsigned long kInitSaveResolutionName = 0x40000000;
  64   const unsigned long kInitSaveDownloadFonts  = 0x80000000;
  65   const unsigned long kInitSaveAll            = 0xFFFFFFFF;
  66
  67   /* Print Option Flags for Bit Field*/
  68   const long kPrintOddPages     = 0x00000001;
  69   const long kPrintEvenPages    = 0x00000002;
  70   const long kEnableSelectionRB = 0x00000004;
  71
  72   /* Print Range Enums */
  73   const long kRangeAllPages           = 0;
  74   const long kRangeSpecifiedPageRange = 1;
  75   const long kRangeSelection          = 2;
  76   const long kRangeFocusFrame         = 3;
  77
  78   /* Justification Enums */
  79   const long kJustLeft   = 0;
  80   const long kJustCenter = 1;
  81   const long kJustRight  = 2;
  82
  83   /**
  84    * FrameSet Default Type Constants
  85    */
  86   const short kUseInternalDefault    = 0;
  87   const short kUseSettingWhenPossible = 1;
  88
  89   /**
  90    * Page Size Type Constants
  91    */
  92   const short kPaperSizeNativeData  = 0;
  93   const short kPaperSizeDefined     = 1;
  94
  95   /**
  96    * Page Size Unit Constants
  97    */
  98   const short kPaperSizeInches      = 0;
  99   const short kPaperSizeMillimeters = 1;
 100
 101   /**
 102    * Orientation Constants
 103    */
 104   const short kPortraitOrientation  = 0;
 105   const short kLandscapeOrientation = 1;
 106
 107   /**
 108    * Print Frame Constants
 109    */
 110   const short kNoFrames      = 0;
 111   const short kFramesAsIs    = 1;
 112   const short kSelectedFrame = 2;
 113   const short kEachFrameSep  = 3;
 114
 115   /**
 116    * How to Enable Frame Set Printing Constants
 117    */
 118   const short kFrameEnableNone        = 0;
 119   const short kFrameEnableAll         = 1;
 120   const short kFrameEnableAsIsAndEach = 2;
 121
 122   /**
 123    * Output file format
 124    */
 125   const short kOutputFormatNative = 0;
 126   const short kOutputFormatPS     = 1;
 127   const short kOutputFormatPDF    = 2;
 128
 129   /**
 130    * Set PrintOptions
 131    */
 132   void SetPrintOptions(in int32_t aType, in boolean aTurnOnOff);
 133
 134   /**
 135    * Get PrintOptions
 136    */
 137   boolean GetPrintOptions(in int32_t aType);
 138
 139   /**
 140    * Set PrintOptions Bit field
 141    */
 142   int32_t GetPrintOptionsBits();
 143
 144   /**
 145    * Get the page size in twips, considering the
 146    * orientation (portrait or landscape).
 147    */
 148   void GetEffectivePageSize(out double aWidth, out double aHeight);
 149
 150   /**
 151    * Makes a new copy
 152    */
 153     nsIPrintSettings clone();
 154
 155   /**
 156    * Assigns the internal values from the "in" arg to the current object
 157    */
 158     void assign(in nsIPrintSettings aPS);
 159
 160   /**
 161    * Data Members
 162    */
 163   [noscript] attribute nsIPrintSession printSession; /* We hold a weak reference */
 164
 165   attribute long    startPageRange;
 166   attribute long    endPageRange;
 167
 168   /**
 169    * The edge measurements define the positioning of the headers
 170    * and footers on the page. They're measured as an offset from
 171    * the "unwriteable margin" (described below).
 172    */
 173   attribute double  edgeTop;     /*  these are in inches */
 174   attribute double  edgeLeft;
 175   attribute double  edgeBottom;
 176   attribute double  edgeRight;
 177
 178   /**
 179    * The margins define the positioning of the content on the page.
 180    * They're treated as an offset from the "unwriteable margin"
 181    * (described below).
 182    */
 183   attribute double  marginTop;     /*  these are in inches */
 184   attribute double  marginLeft;
 185   attribute double  marginBottom;
 186   attribute double  marginRight;
 187   /**
 188    * The unwriteable margin defines the printable region of the paper, creating
 189    * an invisible border from which the edge and margin attributes are measured.
 190    */
 191   attribute double  unwriteableMarginTop;     /*  these are in inches */
 192   attribute double  unwriteableMarginLeft;
 193   attribute double  unwriteableMarginBottom;
 194   attribute double  unwriteableMarginRight;
 195
 196   attribute double  scaling;      /* values 0.0 - 1.0 */
 197   attribute boolean printBGColors; /* Print Background Colors */
 198   attribute boolean printBGImages; /* Print Background Images */
 199
 200   attribute short   printRange;
 201
 202   attribute wstring title;
 203   attribute wstring docURL;
 204
 205   attribute wstring headerStrLeft;
 206   attribute wstring headerStrCenter;
 207   attribute wstring headerStrRight;
 208
 209   attribute wstring footerStrLeft;
 210   attribute wstring footerStrCenter;
 211   attribute wstring footerStrRight;
 212
 213   attribute short   howToEnableFrameUI;  /* indicates how to enable the frameset UI            */
 214   attribute boolean isCancelled;         /* indicates whether the print job has been cancelled */
 215   attribute short   printFrameTypeUsage; /* indicates whether to use the interal value or not  */
 216   attribute short   printFrameType;
 217   attribute boolean printSilent;             /* print without putting up the dialog */
 218   attribute boolean shrinkToFit;             /* shrinks content to fit on page      */
 219   attribute boolean showPrintProgress;   /* indicates whether the progress dialog should be shown */
 220
 221   /* Additional XP Related */
 222   attribute wstring paperName;     /* name of paper */
 223   attribute short   paperSizeType; /* use native data or is defined here */
 224   attribute short   paperData;     /* native data value */
 225   attribute double  paperWidth;    /* width of the paper in inches or mm */
 226   attribute double  paperHeight;   /* height of the paper in inches or mm */
 227   attribute short   paperSizeUnit; /* paper is in inches or mm */
 228
 229   attribute wstring plexName;      /* name of plex mode (like "simplex", "duplex",
 230                                     * "tumble" and various custom values) */
 231
 232   attribute wstring colorspace;    /* device-specific name of colorspace, overrides |printInColor| */
 233   attribute wstring resolutionName;/* device-specific identifer of resolution or quality
 234                                     * (like "600", "600x300", "600x300x12", "high-res",
 235                                     * "med-res". "low-res", etc.) */
 236   attribute boolean downloadFonts; /* enable font download to printer? */
 237
 238   attribute boolean printReversed;
 239   attribute boolean printInColor;  /* a false means grayscale */
 240   attribute long    orientation;   /*  see orientation consts */
 241   attribute wstring printCommand;
 242   attribute long    numCopies;
 243
 244   attribute wstring printerName;   /* name of destination printer */
 245
 246   attribute boolean printToFile;
 247   attribute wstring toFileName;
 248   attribute short   outputFormat;
 249
 250   attribute long    printPageDelay; /* in milliseconds */
 251
 252   attribute long    resolution;     /* print resolution (dpi) */
 253
 254   attribute long    duplex;         /* duplex mode */
 255
 256   /* initialize helpers */
 257   /**
 258    * This attribute tracks whether the PS has been initialized
 259    * from a printer specified by the "printerName" attr.
 260    * If a different name is set into the "printerName"
 261    * attribute than the one it was initialized with the PS
 262    * will then get intialized from that printer.
 263    */
 264   attribute boolean isInitializedFromPrinter;
 265
 266   /**
 267    * This attribute tracks whether the PS has been initialized
 268    * from prefs. If a different name is set into the "printerName"
 269    * attribute than the one it was initialized with the PS
 270    * will then get intialized from prefs again.
 271    */
 272   attribute boolean isInitializedFromPrefs;
 273
 274   /**
 275    * This attribute tracks if the settings made on the margin box is
 276    * stored in the prefs or not.
 277    */
 278   attribute boolean persistMarginBoxSettings;
 279
 280   /* C++ Helper Functions */
 281   [noscript] void SetMarginInTwips(in nsNativeIntMarginRef aMargin);
 282   [noscript] void SetEdgeInTwips(in nsNativeIntMarginRef aEdge);
 283   /* Purposely made this an "in" arg */
 284   [noscript] void GetMarginInTwips(in nsNativeIntMarginRef aMargin);
 285   [noscript] void GetEdgeInTwips(in nsNativeIntMarginRef aEdge);
 286
 287   /**
 288    * We call this function so that anything that requires a run of the event loop
 289    * can do so safely. The print dialog runs the event loop but in silent printing
 290    * that doesn't happen.
 291    *
 292    * Either this or ShowPrintDialog (but not both) MUST be called by the print engine
 293    * before printing, otherwise printing can fail on some platforms.
 294    */
 295   [noscript] void SetupSilentPrinting();
 296
 297   /**
 298    * Sets/Gets the "unwriteable margin" for the page format.  This defines
 299    * the boundary from which we'll measure the EdgeInTwips and MarginInTwips
 300    * attributes, to place the headers and content, respectively.
 301    *
 302    * Note: Implementations of SetUnwriteableMarginInTwips should handle
 303    * negative margin values by falling back on the system default for
 304    * that margin.
 305    */
 306   [noscript] void SetUnwriteableMarginInTwips(in nsNativeIntMarginRef aEdge);
 307   [noscript] void GetUnwriteableMarginInTwips(in nsNativeIntMarginRef aEdge);
 308
 309   /**
 310    * Get more accurate print ranges from the superior interval
 311    * (startPageRange, endPageRange). The aPages array is populated with a
 312    * list of pairs (start, end), where the endpoints are included. The print
 313    * ranges (start, end), must not overlap and must be in the
 314    * (startPageRange, endPageRange) scope.
 315    *
 316    * If there are no print ranges the aPages array is cleared.
 317    */
 318   [noscript] void GetPageRanges(in IntegerArray aPages);
 319 };