diff options
Diffstat (limited to 'widget/nsIPrintSettings.idl')
| -rw-r--r-- | widget/nsIPrintSettings.idl | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/widget/nsIPrintSettings.idl b/widget/nsIPrintSettings.idl new file mode 100644 index 0000000000..efed9efce6 --- /dev/null +++ b/widget/nsIPrintSettings.idl @@ -0,0 +1,405 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* 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" + +%{ C++ +#include "nsMargin.h" +#include "nsTArray.h" + +namespace mozilla { +struct PrintSettingsInitializer; +} +%} + +/** + * Native types + */ +native nsNativeIntMargin(nsIntMargin); +[ref] native nsNativeIntMarginRef(nsIntMargin); +native PrintSettingsInitializer(mozilla::PrintSettingsInitializer); + +interface nsIOutputStream; + +/** + * Simplified graphics interface for JS rendering. + */ +[scriptable, builtinclass, uuid(ecc5cbad-57fc-4731-b0bd-09e865bd62ad)] +interface nsIPrintSettings : nsISupports +{ + /** + * PrintSettings to be Saved Navigation Constants + */ + /* Flag 0x00000001 is unused */ + const unsigned long kInitSaveHeaderLeft = 0x00000002; + const unsigned long kInitSaveHeaderCenter = 0x00000004; + const unsigned long kInitSaveHeaderRight = 0x00000008; + const unsigned long kInitSaveFooterLeft = 0x00000010; + const unsigned long kInitSaveFooterCenter = 0x00000020; + const unsigned long kInitSaveFooterRight = 0x00000040; + const unsigned long kInitSaveBGColors = 0x00000080; + const unsigned long kInitSaveBGImages = 0x00000100; + const unsigned long kInitSavePaperSize = 0x00000200; + /* Flag 0x00000400 is unused */ + const unsigned long kInitSaveDuplex = 0x00000800; + /* Flag 0x00001000 is unused */ + /* Flag 0x00002000 is unused */ + const unsigned long kInitSaveUnwriteableMargins = 0x00004000; + const unsigned long kInitSaveEdges = 0x00008000; + + const unsigned long kInitSaveReversed = 0x00010000; + const unsigned long kInitSaveInColor = 0x00020000; + const unsigned long kInitSaveOrientation = 0x00040000; + + const unsigned long kInitSavePrinterName = 0x00100000; + const unsigned long kInitSavePrintToFile = 0x00200000; + const unsigned long kInitSaveToFileName = 0x00400000; + const unsigned long kInitSavePageDelay = 0x00800000; + const unsigned long kInitSaveMargins = 0x01000000; + /* Flag 0x02000000 is unused */ + + const unsigned long kInitSaveShrinkToFit = 0x08000000; + const unsigned long kInitSaveScaling = 0x10000000; + + const unsigned long kInitSaveAll = 0xFFFFFFFF; + + // These settings should be read from global prefs. Other settings should be + // read only from printer-specific prefs. + const unsigned long kGlobalSettings = + kInitSaveHeaderLeft | kInitSaveHeaderCenter | kInitSaveHeaderRight | + kInitSaveFooterLeft | kInitSaveFooterCenter | kInitSaveFooterRight | + kInitSaveEdges | kInitSaveReversed | kInitSaveInColor | + kInitSaveBGColors | kInitSaveBGImages | kInitSaveShrinkToFit; + + // These settings may be changed by native print dialog and should be + // persisted when changed. + const unsigned long kPrintDialogPersistSettings = + kGlobalSettings | kInitSavePaperSize | kInitSaveDuplex | + kInitSaveEdges | kInitSaveReversed | kInitSaveInColor | + kInitSaveOrientation | kInitSavePageDelay | kInitSaveMargins | + kInitSaveShrinkToFit | kInitSaveScaling; + + /* Justification Enums */ + const long kJustLeft = 0; + const long kJustCenter = 1; + const long kJustRight = 2; + + /** Page Size Unit Constants */ + const short kPaperSizeInches = 0; + const short kPaperSizeMillimeters = 1; + + /** Orientation Constants */ + const short kPortraitOrientation = 0; + const short kLandscapeOrientation = 1; + + /** Output file format */ + const short kOutputFormatNative = 0; + const short kOutputFormatPDF = 2; + + /** Output destination */ + cenum OutputDestinationType : 8 { + kOutputDestinationPrinter = 0, + kOutputDestinationFile = 1, + kOutputDestinationStream = 2, + }; + + /** + * Duplex printing options. + * + * Note that other libraries refer to equivalent duplex settings using + * various sets of terminology. This can be confusing and inconsistent both + * with other libraries, and with the behavior that these terms intend to describe. + * + * kDuplexNone is equivalent to Simplex. Thankfully, both of these terms are + * consistent with the behavior that they describe, which is to have single-sided + * printing per sheet. + * + * kDuplexFlipOnLongEdge is equivalent to the following platform-specific constants: + * CUPS/macOS: NoTumble + * Windows: DMDUP_VERTICAL + * GTK: GTK_PRINT_DUPLEX_HORIZONTAL + * + * kDuplexFlipOnShortEdge is equivalent to the following platform-specific constants: + * CUPS/macOS: Tumble + * Windows: DMDUP_HORIZONTAL + * GTK: GTK_PRINT_DUPLEX_VERTICAL + * + * + * Notice that the GTK and Windows constants have opposite meanings for + * VERTICAL and HORIZONTAL. + * + * To make matters more confusing, these platform-specific terms describe different + * behavior (from the user's perspective) depending on whether the sheet is in + * portrait vs. landscape orientation. + * + * For example, the generic term "tumble" describes behavior where a sheet flips over + * a binding on the top edge (like a calendar). This requires that the back side of + * the sheet is printed upside down with respect to the front side of the sheet, + * so that its content appears upright to the reader when they tumble-flip the + * sheet over the top-edge binding. + * + * However, the CUPS/macOS Tumble setting only inverts the back side of the + * sheet in portrait orientation. When you switch to landscape orientation, the + * Tumble setting behaves like a book-like sheet flip, where the front and back + * sides of the sheet are both printed upright with respect to each other. + * + * This is why it is more consistent and more clear to think of these terms + * with regard to sheets being bound on the long edge or the short edge. + * + * kDuplexFlipOnLongEdge + Portrait = book-like flip (front/back same direction) + * kDuplexFlipOnLongEdge + Landscape = calendar-like flip (front/back inverted) + * + * kDuplexFlipOnShortEdge + Portrait = calendar-like flip (front/back inverted) + * kDuplexFlipOnShortEdge + Landscape = book-like flip (front/back same direction) + * + * The long-edge and short-edge terminology unfortunately breaks down when printing + * with square sheet dimensions. Thankfully this edge case (hah) is quite uncommon, + * since most standard printing paper dimensions are not square. Such a paper size + * would even break the uniformly used portrait and landscape terminology. + */ + const short kDuplexNone = 0; + const short kDuplexFlipOnLongEdge = 1; + const short kDuplexFlipOnShortEdge = 2; + + /** + * Get the page size in twips, considering the + * orientation (portrait or landscape). + */ + void GetEffectivePageSize(out double aWidth, out double aHeight); + + /** + * Get the printed sheet size in twips, considering both the user-specified + * orientation (portrait or landscape) *as well as* the fact that we might be + * inverting the orientation to account for 2 or 6 pages-per-sheet. + * + * This API will usually behave the same (& return the same thing) as + * GetEffectivePageSize, *except for* when we are printing with 2 or 6 + * pages-per-sheet, in which case the return values (aWidth & aHeight) will + * be swapped with respect to what GetEffectivePageSize would return. + * + * Callers should use this method rather than GetEffectivePageSize when they + * really do want the size of the sheet of paper to be printed, rather than + * the possibly-"virtualized"-via-pages-per-sheet page size. + */ + [noscript, notxpcom, nostdcall] void GetEffectiveSheetSize(out double aWidth, + out double aHeight); + + /** + * Get the orientation of a printed sheet. This is usually the same as the + * 'orientation' attribute (which is the orientation of individual pages), + * except when we're printing with 2 or 6 pages-per-sheet, in which case + * it'll be the opposite value. + * + * Note that this value is not independently settable. Its value is fully + * determined by the 'orientation' and 'numPagesPerSheet' attributes. + */ + [noscript, notxpcom, nostdcall] long GetSheetOrientation(); + + /** + * Convenience getter, which returns true IFF the value of `numPagesPerSheet` + * would require us to orient the pages orthogonally to the sheet in order + * to make best use of the space on the sheet. Specifically, this returns + * true IFF `numPagesPerSheet` is set to 2 or 6 pages-per-sheet. + */ + [noscript, notxpcom, nostdcall] bool HasOrthogonalPagesPerSheet(); + + /** + * Makes a new copy + */ + nsIPrintSettings clone(); + + /** + * Assigns the internal values from the "in" arg to the current object + */ + void assign(in nsIPrintSettings aPS); + + /** + * Returns true if the settings will result in an equivalent preview and + * therefore print. The printer name is ignored and it allows for a small + * delta in sizes to allow for rounding differences. + */ + bool equivalentTo(in nsIPrintSettings aPrintSettings); + + /** + * The edge measurements define the positioning of the headers + * and footers on the page. They're treated as an offset from the edges of + * the page, but are forced to be at least the "unwriteable margin" + * (described below). + */ + attribute double edgeTop; /* these are in inches */ + attribute double edgeLeft; + attribute double edgeBottom; + attribute double edgeRight; + + /** + * The margins define the positioning of the content on the page. + * and footers on the page. They're treated as an offset from the edges of + * the page, but are forced to be at least the "unwriteable margin," unless + * set to be ignored (described below). + */ + attribute double marginTop; /* these are in inches */ + attribute double marginLeft; + attribute double marginBottom; + attribute double marginRight; + /** + * The unwriteable margin defines the printable region of the paper. + */ + attribute double unwriteableMarginTop; /* these are in inches */ + attribute double unwriteableMarginLeft; + attribute double unwriteableMarginBottom; + attribute double unwriteableMarginRight; + + attribute double scaling; /* values 0.0 - 1.0 */ + [infallible] attribute boolean printBGColors; /* Print Background Colors */ + [infallible] attribute boolean printBGImages; /* Print Background Images */ + + /** + * Whether @page rule margins should be honored or not. If the @page + * rule sets its margins to zero, we automatically ignore unwriteable + * margins, but nonzero values will be clamped to unwriteable margins. + */ + [infallible] attribute boolean honorPageRuleMargins; + + /** + * Whether @page rule size should be used for the output paper size. + */ + [infallible] attribute boolean usePageRuleSizeAsPaperSize; + + /** + * Whether unwritable margins should be ignored. This should be set when + * when the user explicitly requests "Margins: None", e.g. for documents + * where accurate scaling matters. Note: While `honorPageRuleMargins` and + * this flag can't be set at the same time through the UI, doing so will + * cause even the nonzero @page rule margins to ignore unwriteable margins. + */ + [infallible] attribute boolean ignoreUnwriteableMargins; + + /** Whether to draw guidelines showing the margin settings */ + [infallible] attribute boolean showMarginGuides; + + /** Whether to only print the selected nodes */ + [infallible] attribute boolean printSelectionOnly; + + attribute AString title; + attribute AString docURL; + + attribute AString headerStrLeft; + attribute AString headerStrCenter; + attribute AString headerStrRight; + + attribute AString footerStrLeft; + attribute AString footerStrCenter; + attribute AString footerStrRight; + + attribute boolean printSilent; /* print without putting up the dialog */ + [infallible] attribute boolean shrinkToFit; /* shrinks content to fit on page */ + + /* Additional XP Related */ + attribute AString paperId; /* identifier of paper (not display name) */ + attribute double paperWidth; /* width of the paper in inches or mm */ + attribute double paperHeight; /* height of the paper in inches or mm */ + attribute short paperSizeUnit; /* paper is in inches or mm */ + + attribute boolean printReversed; + [infallible] attribute boolean printInColor; /* a false means grayscale */ + attribute long orientation; /* see orientation consts */ + attribute long numCopies; + + /** + * For numPagesPerSheet, we support these values: 1, 2, 4, 6, 9, 16. + * + * Unsupported values will be treated internally as 1 page per sheet, and + * will trigger assertion failures in debug builds. + */ + attribute long numPagesPerSheet; + + /** Output device information */ + [infallible] attribute nsIPrintSettings_OutputDestinationType outputDestination; + [infallible] attribute short outputFormat; + + /** + * If outputDestination==kOutputDestinationPrinter, this is set to the name + * of the printer that the print output should be saved to, but only in the + * parent process (we don't want to leak printer names to potentially + * compromised content processes). + */ + attribute AString printerName; + + /** + * If outputDestination==kOutputDestinationFile, this is set to the path + * of the file that the print output should be saved to, but only in the + * parent process (we don't want to leak system paths to potentially + * compromised content processes). + */ + attribute AString toFileName; + + attribute nsIOutputStream outputStream; /* for kOutputDestinationPrinter */ + + [infallible] attribute long printPageDelay; /* in milliseconds */ + + [infallible] attribute long resolution; /* print resolution (dpi) */ + + [infallible] attribute long duplex; /* duplex mode */ + + /* initialize helpers */ + /** + * This attribute tracks whether the PS has been initialized + * from a printer specified by the "printerName" attr. + * If a different name is set into the "printerName" + * attribute than the one it was initialized with the PS + * will then get initialized from that printer. + */ + attribute boolean isInitializedFromPrinter; + + /** + * This attribute tracks whether the PS has been initialized + * from prefs. If a different name is set into the "printerName" + * attribute than the one it was initialized with the PS + * will then get initialized from prefs again. + */ + attribute boolean isInitializedFromPrefs; + + /* C++ Helper Functions */ + [noscript] void SetMarginInTwips(in nsNativeIntMarginRef aMargin); + [noscript] void SetEdgeInTwips(in nsNativeIntMarginRef aEdge); + [noscript, notxpcom, nostdcall] nsNativeIntMargin GetMarginInTwips(); + [noscript, notxpcom, nostdcall] nsNativeIntMargin GetEdgeInTwips(); + + /** + * Sets/Gets the "unwriteable margin" for the page format. This defines + * the boundary from which we'll measure the EdgeInTwips and MarginInTwips + * attributes, to place the headers and content, respectively. + * + * Note: Implementations of SetUnwriteableMarginInTwips should handle + * negative margin values by falling back on the system default for + * that margin. + */ + [noscript] void SetUnwriteableMarginInTwips(in nsNativeIntMarginRef aEdge); + [noscript, notxpcom, nostdcall] nsNativeIntMargin GetUnwriteableMarginInTwips(); + + /** + * Get more accurate print ranges from the superior interval + * (startPageRange, endPageRange). The aPages array is populated with a + * list of pairs (start, end), where the endpoints are included. The print + * ranges (start, end), must not overlap and must be in the + * (startPageRange, endPageRange) scope. + * + * If there are no print ranges the aPages array is empty. + */ + attribute Array<long> pageRanges; + + /** + * Get a PrintSettingsInitializer populated with the relevant current settings. + */ + [notxpcom, nostdcall] PrintSettingsInitializer getSettingsInitializer(); + +%{C++ + static bool IsPageSkipped(int32_t aPageNum, const nsTArray<int32_t>& aRanges); +%} +}; + +%{ C++ +already_AddRefed<nsIPrintSettings> CreatePlatformPrintSettings(const mozilla::PrintSettingsInitializer&); +%} |