Class PaperClips


  • public class PaperClips
    extends java.lang.Object
    This class contains static constants and methods for preparing and printing documents. Methods in this class supersede those in PrintUtil.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) static boolean debug  
      static int ORIENTATION_DEFAULT
      Indicates that the printer's default page orientation should be used.
      static int ORIENTATION_LANDSCAPE
      Indicates landscape page orientation.
      static int ORIENTATION_PORTRAIT
      Indicates portrait page orientation.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private PaperClips()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      private static void cancelJob​(org.eclipse.swt.printing.Printer printer)  
      private static org.eclipse.swt.graphics.GC createAndConfigureGC​(org.eclipse.swt.printing.Printer printer)  
      private static void disposeUnusedPages​(PrintPiece[] pages, int startPage, int endPage)  
      static void endDummyJob​(org.eclipse.swt.printing.Printer printer)
      Ends a dummy job on the given Printer if the platform requires a dummy job.
      static void error​(int code)
      Triggers an appropriate exception based on the passed in error code.
      static void error​(int code, java.lang.String detail)
      Triggers an appropriate exception based on the passed in error code.
      static void error​(java.lang.String detail)
      Triggers an unspecified exception with the passed in detail.
      static boolean getDebug()
      EXPERIMENTAL: Returns whether debug mode is enabled.
      static org.eclipse.swt.printing.PrinterData getDefaultPrinterData()
      Returns a PrinterData for the system-default printer, or the first printer if no default printer is configured.
      static org.eclipse.swt.graphics.Rectangle getMarginBounds​(Margins margins, org.eclipse.swt.printing.Printer printer)
      Returns the bounding rectangle of the printable area which is inside the given margins on the paper.
      static PageEnumeration getPageEnumeration​(PrintJob printJob, org.eclipse.swt.printing.Printer printer, org.eclipse.swt.graphics.GC gc)
      Returns a PageEnumeration for the passed in PrintJob on the given Printer, using the given GC.
      static PrintPiece[] getPages​(PrintJob printJob, org.eclipse.swt.printing.Printer printer)
      Processes the print job and returns an array of pages for the given printer device.
      private static PrintPiece[] getPages​(PrintJob printJob, org.eclipse.swt.printing.Printer printer, org.eclipse.swt.graphics.GC gc)  
      static org.eclipse.swt.graphics.Rectangle getPaperBounds​(org.eclipse.swt.printing.Printer printer)
      Returns the bounding rectangle of the paper, including non-printable margins.
      static org.eclipse.swt.graphics.Rectangle getPrintableBounds​(org.eclipse.swt.printing.Printer printer)
      Returns the bounding rectangle of the printable area on the paper.
      private static boolean isCarbon()  
      private static boolean isGTK()  
      static PrintPiece next​(PrintIterator iterator, int width, int height)
      Calls iterator.next(width, height) and returns the result.
      static void print​(PrintJob printJob, org.eclipse.swt.printing.Printer printer)
      Prints the print job to the given printer.
      static void print​(PrintJob printJob, org.eclipse.swt.printing.PrinterData printerData)
      Prints the print job to the given printer.
      private static void print​(PrintJob printJob, org.eclipse.swt.printing.Printer printer, org.eclipse.swt.graphics.GC gc)
      Prints the print job to the specified printer using the GC.
      private static void printPages​(org.eclipse.swt.printing.Printer printer, org.eclipse.swt.graphics.GC gc, PrintPiece[] pages, int startPage, int endPage, int collatedCopies, int noncollatedCopies)  
      static void setDebug​(boolean debug)
      EXPERIMENTAL: Sets whether debug mode is enabled.
      static void startDummyJob​(org.eclipse.swt.printing.Printer printer, java.lang.String name)
      Starts a dummy job on the given Printer if the platform requires it.
      private static void startJob​(org.eclipse.swt.printing.Printer printer, java.lang.String jobName)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • debug

        static boolean debug
      • ORIENTATION_DEFAULT

        public static final int ORIENTATION_DEFAULT
        Indicates that the printer's default page orientation should be used.
        See Also:
        Constant Field Values
      • ORIENTATION_PORTRAIT

        public static final int ORIENTATION_PORTRAIT
        Indicates portrait page orientation.
        See Also:
        Constant Field Values
      • ORIENTATION_LANDSCAPE

        public static final int ORIENTATION_LANDSCAPE
        Indicates landscape page orientation.
        See Also:
        Constant Field Values
    • Constructor Detail

      • PaperClips

        private PaperClips()
    • Method Detail

      • error

        public static void error​(int code)
        Triggers an appropriate exception based on the passed in error code.
        Parameters:
        code - the SWT error code.
      • error

        public static void error​(java.lang.String detail)
        Triggers an unspecified exception with the passed in detail.
        Parameters:
        detail - more information about error.
      • error

        public static void error​(int code,
                                 java.lang.String detail)
        Triggers an appropriate exception based on the passed in error code.
        Parameters:
        code - the SWT error code.
        detail - more information about error.
      • setDebug

        public static void setDebug​(boolean debug)
        EXPERIMENTAL: Sets whether debug mode is enabled. This mode may be used for troubleshooting documents that cannot be laid out for some reason (e.g. "Cannot layout page x" error occurs).

        THIS API IS EXPERIMENTAL AND MAY BE REMOVED OR CHANGED IN THE FUTURE.

        Parameters:
        debug - true to enable debug mode, false to disable it.
      • getDebug

        public static boolean getDebug()
        EXPERIMENTAL: Returns whether debug mode is enabled.

        THIS API IS EXPERIMENTAL AND MAY BE REMOVED OR CHANGED IN THE FUTURE.

        Returns:
        whether debug mode is enabled.
      • getDefaultPrinterData

        public static org.eclipse.swt.printing.PrinterData getDefaultPrinterData()
        Returns a PrinterData for the system-default printer, or the first printer if no default printer is configured.
        Returns:
        a PrinterData for the system-default printer, or the first printer if no default printer is configured.
      • next

        public static PrintPiece next​(PrintIterator iterator,
                                      int width,
                                      int height)
        Calls iterator.next(width, height) and returns the result. This method checks multiple conditions to ensure proper usage and behavior of PrintIterators.

        This method is intended to be used by PrintIterator classes, as a results-checking alternative to calling next(int, int) directly on the target iterator. All PrintIterator classes in the PaperClips library use this method instead of directly calling the PrintIterator.next(int, int) method.

        Parameters:
        iterator - the PrintIterator
        width - the available width.
        height - the available height.
        Returns:
        the next portion of the Print, or null if the width and height are not enough to display any of the iterator's contents.
      • print

        public static void print​(PrintJob printJob,
                                 org.eclipse.swt.printing.PrinterData printerData)
        Prints the print job to the given printer. This method constructs a Printer, forwards to print(PrintJob, Printer), and disposes the printer before returning.
        Parameters:
        printJob - the print job.
        printerData - the PrinterData of the selected printer.
      • print

        public static void print​(PrintJob printJob,
                                 org.eclipse.swt.printing.Printer printer)
        Prints the print job to the given printer.
        Parameters:
        printJob - the print job.
        printer - the printer device.
      • startJob

        private static void startJob​(org.eclipse.swt.printing.Printer printer,
                                     java.lang.String jobName)
      • cancelJob

        private static void cancelJob​(org.eclipse.swt.printing.Printer printer)
      • createAndConfigureGC

        private static org.eclipse.swt.graphics.GC createAndConfigureGC​(org.eclipse.swt.printing.Printer printer)
      • print

        private static void print​(PrintJob printJob,
                                  org.eclipse.swt.printing.Printer printer,
                                  org.eclipse.swt.graphics.GC gc)
        Prints the print job to the specified printer using the GC. This method does not manage the print job lifecycle (it does not call startJob or endJob).
        Parameters:
        printJob - the print job
        printer - the printer
        gc - the GC
      • printPages

        private static void printPages​(org.eclipse.swt.printing.Printer printer,
                                       org.eclipse.swt.graphics.GC gc,
                                       PrintPiece[] pages,
                                       int startPage,
                                       int endPage,
                                       int collatedCopies,
                                       int noncollatedCopies)
      • disposeUnusedPages

        private static void disposeUnusedPages​(PrintPiece[] pages,
                                               int startPage,
                                               int endPage)
      • getPages

        public static PrintPiece[] getPages​(PrintJob printJob,
                                            org.eclipse.swt.printing.Printer printer)
        Processes the print job and returns an array of pages for the given printer device. Each element in the returned array has already had the page orientation and page margins applied. Therefore, when calling the paint(GC, int, int) method on each page, the printer's trim should be provided as the x and y arguments. In other words, the trim is taken as a minimum margin while applying calculating margins, but the position where the page's content is drawn is determined solely by the margin, and is not offset by the trim. This behavior is helpful for screen display, and is already compensated for in the print(PrintJob, Printer) method.
        Parameters:
        printer - the printing device.
        printJob - the print job.
        Returns:
        an array of all pages of the print job. Each element of the returned array represents one page in the printed document.
      • startDummyJob

        public static void startDummyJob​(org.eclipse.swt.printing.Printer printer,
                                         java.lang.String name)
        Starts a dummy job on the given Printer if the platform requires it. Dummy jobs allow the various Print components of PaperClips to perform measurements required for document layout, without actually sending a job to the printer. Only Mac OS X Carbon and Linux GTK+ are known to require dummy jobs.
        Parameters:
        printer - the Printer hosting the dummy print job.
        name - the name of the dummy print job.
      • endDummyJob

        public static void endDummyJob​(org.eclipse.swt.printing.Printer printer)
        Ends a dummy job on the given Printer if the platform requires a dummy job.
        Parameters:
        printer - the Printer hosting the dummy print job.
      • isCarbon

        private static boolean isCarbon()
      • isGTK

        private static boolean isGTK()
      • getPages

        private static PrintPiece[] getPages​(PrintJob printJob,
                                             org.eclipse.swt.printing.Printer printer,
                                             org.eclipse.swt.graphics.GC gc)
      • getPageEnumeration

        public static PageEnumeration getPageEnumeration​(PrintJob printJob,
                                                         org.eclipse.swt.printing.Printer printer,
                                                         org.eclipse.swt.graphics.GC gc)
        Returns a PageEnumeration for the passed in PrintJob on the given Printer, using the given GC. The Printer and GC must not be disposed while the enumeration is in use.
        Parameters:
        printJob - the print job
        printer - the Printer device, which must not be disposed while the PageEnumeration is in use.
        gc - the GC, which must not be disposed while the PageEnumeration is in use.
        Returns:
        a PageEnumeration for the passed in PrintJob.
      • getPaperBounds

        public static org.eclipse.swt.graphics.Rectangle getPaperBounds​(org.eclipse.swt.printing.Printer printer)
        Returns the bounding rectangle of the paper, including non-printable margins.
        Parameters:
        printer - the printer device.
        Returns:
        a rectangle whose edges correspond to the edges of the paper.
      • getPrintableBounds

        public static org.eclipse.swt.graphics.Rectangle getPrintableBounds​(org.eclipse.swt.printing.Printer printer)
        Returns the bounding rectangle of the printable area on the paper.
        Parameters:
        printer - the printer device.
        Returns:
        the bounding rectangle of the printable area on the paper.
      • getMarginBounds

        public static org.eclipse.swt.graphics.Rectangle getMarginBounds​(Margins margins,
                                                                         org.eclipse.swt.printing.Printer printer)
        Returns the bounding rectangle of the printable area which is inside the given margins on the paper. The printer's minimum margins are reflected in the returned rectangle.
        Parameters:
        printer - the printer device.
        margins - the desired page margins.
        Returns:
        the bounding rectangle on the printable area which is within the margins.