no bug - Bumping Firefox l10n changesets r=release a=l10n-bump DONTBUILD CLOSED TREE
[gecko.git] / widget / nsIPrintSettings.idl
blobefed9efce64a2c7328b6061c451e74476eaecbaa
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/. */
6 #include "nsISupports.idl"
8 %{ C++
9 #include "nsMargin.h"
10 #include "nsTArray.h"
12 namespace mozilla {
13 struct PrintSettingsInitializer;
17 /**
18 * Native types
20 native nsNativeIntMargin(nsIntMargin);
21 [ref] native nsNativeIntMarginRef(nsIntMargin);
22 native PrintSettingsInitializer(mozilla::PrintSettingsInitializer);
24 interface nsIOutputStream;
26 /**
27 * Simplified graphics interface for JS rendering.
29 [scriptable, builtinclass, uuid(ecc5cbad-57fc-4731-b0bd-09e865bd62ad)]
30 interface nsIPrintSettings : nsISupports
32 /**
33 * PrintSettings to be Saved Navigation Constants
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 /* Flag 0x00000400 is unused */
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;
52 const unsigned long kInitSaveReversed = 0x00010000;
53 const unsigned long kInitSaveInColor = 0x00020000;
54 const unsigned long kInitSaveOrientation = 0x00040000;
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 /* Flag 0x02000000 is unused */
63 const unsigned long kInitSaveShrinkToFit = 0x08000000;
64 const unsigned long kInitSaveScaling = 0x10000000;
66 const unsigned long kInitSaveAll = 0xFFFFFFFF;
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;
76 // These settings may be changed by native print dialog and should be
77 // persisted when changed.
78 const unsigned long kPrintDialogPersistSettings =
79 kGlobalSettings | kInitSavePaperSize | kInitSaveDuplex |
80 kInitSaveEdges | kInitSaveReversed | kInitSaveInColor |
81 kInitSaveOrientation | kInitSavePageDelay | kInitSaveMargins |
82 kInitSaveShrinkToFit | kInitSaveScaling;
84 /* Justification Enums */
85 const long kJustLeft = 0;
86 const long kJustCenter = 1;
87 const long kJustRight = 2;
89 /** Page Size Unit Constants */
90 const short kPaperSizeInches = 0;
91 const short kPaperSizeMillimeters = 1;
93 /** Orientation Constants */
94 const short kPortraitOrientation = 0;
95 const short kLandscapeOrientation = 1;
97 /** Output file format */
98 const short kOutputFormatNative = 0;
99 const short kOutputFormatPDF = 2;
101 /** Output destination */
102 cenum OutputDestinationType : 8 {
103 kOutputDestinationPrinter = 0,
104 kOutputDestinationFile = 1,
105 kOutputDestinationStream = 2,
109 * Duplex printing options.
111 * Note that other libraries refer to equivalent duplex settings using
112 * various sets of terminology. This can be confusing and inconsistent both
113 * with other libraries, and with the behavior that these terms intend to describe.
115 * kDuplexNone is equivalent to Simplex. Thankfully, both of these terms are
116 * consistent with the behavior that they describe, which is to have single-sided
117 * printing per sheet.
119 * kDuplexFlipOnLongEdge is equivalent to the following platform-specific constants:
120 * CUPS/macOS: NoTumble
121 * Windows: DMDUP_VERTICAL
122 * GTK: GTK_PRINT_DUPLEX_HORIZONTAL
124 * kDuplexFlipOnShortEdge is equivalent to the following platform-specific constants:
125 * CUPS/macOS: Tumble
126 * Windows: DMDUP_HORIZONTAL
127 * GTK: GTK_PRINT_DUPLEX_VERTICAL
130 * Notice that the GTK and Windows constants have opposite meanings for
131 * VERTICAL and HORIZONTAL.
133 * To make matters more confusing, these platform-specific terms describe different
134 * behavior (from the user's perspective) depending on whether the sheet is in
135 * portrait vs. landscape orientation.
137 * For example, the generic term "tumble" describes behavior where a sheet flips over
138 * a binding on the top edge (like a calendar). This requires that the back side of
139 * the sheet is printed upside down with respect to the front side of the sheet,
140 * so that its content appears upright to the reader when they tumble-flip the
141 * sheet over the top-edge binding.
143 * However, the CUPS/macOS Tumble setting only inverts the back side of the
144 * sheet in portrait orientation. When you switch to landscape orientation, the
145 * Tumble setting behaves like a book-like sheet flip, where the front and back
146 * sides of the sheet are both printed upright with respect to each other.
148 * This is why it is more consistent and more clear to think of these terms
149 * with regard to sheets being bound on the long edge or the short edge.
151 * kDuplexFlipOnLongEdge + Portrait = book-like flip (front/back same direction)
152 * kDuplexFlipOnLongEdge + Landscape = calendar-like flip (front/back inverted)
154 * kDuplexFlipOnShortEdge + Portrait = calendar-like flip (front/back inverted)
155 * kDuplexFlipOnShortEdge + Landscape = book-like flip (front/back same direction)
157 * The long-edge and short-edge terminology unfortunately breaks down when printing
158 * with square sheet dimensions. Thankfully this edge case (hah) is quite uncommon,
159 * since most standard printing paper dimensions are not square. Such a paper size
160 * would even break the uniformly used portrait and landscape terminology.
162 const short kDuplexNone = 0;
163 const short kDuplexFlipOnLongEdge = 1;
164 const short kDuplexFlipOnShortEdge = 2;
167 * Get the page size in twips, considering the
168 * orientation (portrait or landscape).
170 void GetEffectivePageSize(out double aWidth, out double aHeight);
173 * Get the printed sheet size in twips, considering both the user-specified
174 * orientation (portrait or landscape) *as well as* the fact that we might be
175 * inverting the orientation to account for 2 or 6 pages-per-sheet.
177 * This API will usually behave the same (& return the same thing) as
178 * GetEffectivePageSize, *except for* when we are printing with 2 or 6
179 * pages-per-sheet, in which case the return values (aWidth & aHeight) will
180 * be swapped with respect to what GetEffectivePageSize would return.
182 * Callers should use this method rather than GetEffectivePageSize when they
183 * really do want the size of the sheet of paper to be printed, rather than
184 * the possibly-"virtualized"-via-pages-per-sheet page size.
186 [noscript, notxpcom, nostdcall] void GetEffectiveSheetSize(out double aWidth,
187 out double aHeight);
190 * Get the orientation of a printed sheet. This is usually the same as the
191 * 'orientation' attribute (which is the orientation of individual pages),
192 * except when we're printing with 2 or 6 pages-per-sheet, in which case
193 * it'll be the opposite value.
195 * Note that this value is not independently settable. Its value is fully
196 * determined by the 'orientation' and 'numPagesPerSheet' attributes.
198 [noscript, notxpcom, nostdcall] long GetSheetOrientation();
201 * Convenience getter, which returns true IFF the value of `numPagesPerSheet`
202 * would require us to orient the pages orthogonally to the sheet in order
203 * to make best use of the space on the sheet. Specifically, this returns
204 * true IFF `numPagesPerSheet` is set to 2 or 6 pages-per-sheet.
206 [noscript, notxpcom, nostdcall] bool HasOrthogonalPagesPerSheet();
209 * Makes a new copy
211 nsIPrintSettings clone();
214 * Assigns the internal values from the "in" arg to the current object
216 void assign(in nsIPrintSettings aPS);
219 * Returns true if the settings will result in an equivalent preview and
220 * therefore print. The printer name is ignored and it allows for a small
221 * delta in sizes to allow for rounding differences.
223 bool equivalentTo(in nsIPrintSettings aPrintSettings);
226 * The edge measurements define the positioning of the headers
227 * and footers on the page. They're treated as an offset from the edges of
228 * the page, but are forced to be at least the "unwriteable margin"
229 * (described below).
231 attribute double edgeTop; /* these are in inches */
232 attribute double edgeLeft;
233 attribute double edgeBottom;
234 attribute double edgeRight;
237 * The margins define the positioning of the content on the page.
238 * and footers on the page. They're treated as an offset from the edges of
239 * the page, but are forced to be at least the "unwriteable margin," unless
240 * set to be ignored (described below).
242 attribute double marginTop; /* these are in inches */
243 attribute double marginLeft;
244 attribute double marginBottom;
245 attribute double marginRight;
247 * The unwriteable margin defines the printable region of the paper.
249 attribute double unwriteableMarginTop; /* these are in inches */
250 attribute double unwriteableMarginLeft;
251 attribute double unwriteableMarginBottom;
252 attribute double unwriteableMarginRight;
254 attribute double scaling; /* values 0.0 - 1.0 */
255 [infallible] attribute boolean printBGColors; /* Print Background Colors */
256 [infallible] attribute boolean printBGImages; /* Print Background Images */
259 * Whether @page rule margins should be honored or not. If the @page
260 * rule sets its margins to zero, we automatically ignore unwriteable
261 * margins, but nonzero values will be clamped to unwriteable margins.
263 [infallible] attribute boolean honorPageRuleMargins;
266 * Whether @page rule size should be used for the output paper size.
268 [infallible] attribute boolean usePageRuleSizeAsPaperSize;
271 * Whether unwritable margins should be ignored. This should be set when
272 * when the user explicitly requests "Margins: None", e.g. for documents
273 * where accurate scaling matters. Note: While `honorPageRuleMargins` and
274 * this flag can't be set at the same time through the UI, doing so will
275 * cause even the nonzero @page rule margins to ignore unwriteable margins.
277 [infallible] attribute boolean ignoreUnwriteableMargins;
279 /** Whether to draw guidelines showing the margin settings */
280 [infallible] attribute boolean showMarginGuides;
282 /** Whether to only print the selected nodes */
283 [infallible] attribute boolean printSelectionOnly;
285 attribute AString title;
286 attribute AString docURL;
288 attribute AString headerStrLeft;
289 attribute AString headerStrCenter;
290 attribute AString headerStrRight;
292 attribute AString footerStrLeft;
293 attribute AString footerStrCenter;
294 attribute AString footerStrRight;
296 attribute boolean printSilent; /* print without putting up the dialog */
297 [infallible] attribute boolean shrinkToFit; /* shrinks content to fit on page */
299 /* Additional XP Related */
300 attribute AString paperId; /* identifier of paper (not display name) */
301 attribute double paperWidth; /* width of the paper in inches or mm */
302 attribute double paperHeight; /* height of the paper in inches or mm */
303 attribute short paperSizeUnit; /* paper is in inches or mm */
305 attribute boolean printReversed;
306 [infallible] attribute boolean printInColor; /* a false means grayscale */
307 attribute long orientation; /* see orientation consts */
308 attribute long numCopies;
311 * For numPagesPerSheet, we support these values: 1, 2, 4, 6, 9, 16.
313 * Unsupported values will be treated internally as 1 page per sheet, and
314 * will trigger assertion failures in debug builds.
316 attribute long numPagesPerSheet;
318 /** Output device information */
319 [infallible] attribute nsIPrintSettings_OutputDestinationType outputDestination;
320 [infallible] attribute short outputFormat;
323 * If outputDestination==kOutputDestinationPrinter, this is set to the name
324 * of the printer that the print output should be saved to, but only in the
325 * parent process (we don't want to leak printer names to potentially
326 * compromised content processes).
328 attribute AString printerName;
331 * If outputDestination==kOutputDestinationFile, this is set to the path
332 * of the file that the print output should be saved to, but only in the
333 * parent process (we don't want to leak system paths to potentially
334 * compromised content processes).
336 attribute AString toFileName;
338 attribute nsIOutputStream outputStream; /* for kOutputDestinationPrinter */
340 [infallible] attribute long printPageDelay; /* in milliseconds */
342 [infallible] attribute long resolution; /* print resolution (dpi) */
344 [infallible] attribute long duplex; /* duplex mode */
346 /* initialize helpers */
348 * This attribute tracks whether the PS has been initialized
349 * from a printer specified by the "printerName" attr.
350 * If a different name is set into the "printerName"
351 * attribute than the one it was initialized with the PS
352 * will then get initialized from that printer.
354 attribute boolean isInitializedFromPrinter;
357 * This attribute tracks whether the PS has been initialized
358 * from prefs. If a different name is set into the "printerName"
359 * attribute than the one it was initialized with the PS
360 * will then get initialized from prefs again.
362 attribute boolean isInitializedFromPrefs;
364 /* C++ Helper Functions */
365 [noscript] void SetMarginInTwips(in nsNativeIntMarginRef aMargin);
366 [noscript] void SetEdgeInTwips(in nsNativeIntMarginRef aEdge);
367 [noscript, notxpcom, nostdcall] nsNativeIntMargin GetMarginInTwips();
368 [noscript, notxpcom, nostdcall] nsNativeIntMargin GetEdgeInTwips();
371 * Sets/Gets the "unwriteable margin" for the page format. This defines
372 * the boundary from which we'll measure the EdgeInTwips and MarginInTwips
373 * attributes, to place the headers and content, respectively.
375 * Note: Implementations of SetUnwriteableMarginInTwips should handle
376 * negative margin values by falling back on the system default for
377 * that margin.
379 [noscript] void SetUnwriteableMarginInTwips(in nsNativeIntMarginRef aEdge);
380 [noscript, notxpcom, nostdcall] nsNativeIntMargin GetUnwriteableMarginInTwips();
383 * Get more accurate print ranges from the superior interval
384 * (startPageRange, endPageRange). The aPages array is populated with a
385 * list of pairs (start, end), where the endpoints are included. The print
386 * ranges (start, end), must not overlap and must be in the
387 * (startPageRange, endPageRange) scope.
389 * If there are no print ranges the aPages array is empty.
391 attribute Array<long> pageRanges;
394 * Get a PrintSettingsInitializer populated with the relevant current settings.
396 [notxpcom, nostdcall] PrintSettingsInitializer getSettingsInitializer();
398 %{C++
399 static bool IsPageSkipped(int32_t aPageNum, const nsTArray<int32_t>& aRanges);
403 %{ C++
404 already_AddRefed<nsIPrintSettings> CreatePlatformPrintSettings(const mozilla::PrintSettingsInitializer&);