Package org.faceless.pdf2.viewer2

Class DocumentPanel

  • All Implemented Interfaces:
    ImageObserver, MenuContainer, Serializable, Accessible
    public class DocumentPanel
extends JPanel

    A DocumentPanel is the basic component that displays a PDF, and may be instantiated on it's own or as part of a PDFViewer. It contains a DocumentViewport and optionally one or more SidePanel objects on the left, and may process PDFActions on the PDF. See the viewer tutorial for more detail on how to use this class and the "viewer" package.

    The following initialization parameters may be specified
    defaultViewportThe class name of the default viewport to use if not specified in the PDF. May be SinglePageDocumentViewport, MultiPageDocumentVieport or a fully-qualified class name of another DocumentViewport
    defaultPageModeThe default "page mode" of the PDF if not set. This may take one of the values for the "pagemode" PDF option, and would typically be "UseThumbs" or "UseOutlines".
    ignoreDocumentPageModetrue or false (the default) - whether to ignore the "pagemode" PDF option in the PDF when choosing which SidePanel t open by default.
    ignoreDocumentTitletrue or false (the default) - whether to ignore the "displaydoctitle" PDF option in the PDF when choosing the text to use for the window title.
    defaultZoomThe default zoom level of the PDF, if not set by a PDF open action. This may be the value "fit", "fitwidth", "fitheight" or a number between 12.5 and 6400 to set the zoom level.
    useNamedSidePanelstrue or false (the default) - whether to show names on the side panel tabs rather than icons.
    sidePanelSizeThe default (and minimum) width of the side panels displayed in this DocumentPanel. The default is 120
    mouseWheelUnitThe number of pixels to adjust the viewport's scrollbar by when using the mouse wheel. The default is 16.
    smoothScrollTimeWhen smoothly scrolling a viewport's scrollbars, the number of ms to animate the scroll over. The default is 500, set to zero to disable.
    smoothScrollDistanceWhen smoothly scrolling a viewport's scrollbars, the maximum number of pixels to try to animate. The default is 500, set to zero to disable.
    earlyCloseWhen closing a DocumentPanel or changing the PDF it contains, the old PDF object remains open and will naturally have its PDF.close() method called during garbage collection. This can lead to problems on Windows platforms; As the PDF may retain a reference to the file it was read from, this prevents the file being deleted until close is called. The earlyClose parameter can be set to close the PDF file immediately the PDF is removed from the DocumentPanel or the panel closed; this will free any resources held by the PDF, and so invalidate any reference to those resources (which may be held elsewhere - for example, if the PDF had its pages moved to another document). So use with caution - by default this value is not set, but set to any non-null value to enable.
    noDirtyDocumentsSet this value to non-null to disable the dirty flag on documents. If disabled, no prompt will appear when trying to close a document that has been modified.
    noDirtyInTitleSet this value to non-null to disable the "*" in the window title when the PDF is flagged as dirty.
    noProgressInTitleSet this value to non-null to disable the load-progress indicator in the window title when the PDF is linearized and only partially loaded.
    respectSignatureCertificationIf true, any restrictions found on a certified signature in the PDF will be honoured - for example, if the PDF being displayed has nochanges set then no changes will be allowed to the PDF through the viewer
    viewportBorderColorCan be set to the Color to draw the border around the pages in the viewport, specified as a hex value. The default value is "666666", which is a dark gray. If the specified value has 8 digits, the first two hex digits are used as the alpha value. A value of "none" or "transparent" will not draw the border.
    viewportShadowColorCan be set to the Color to draw the shadow below the pages in the viewport, specified as a hex value. The default value is "80666666", which is a translucent dark gray. If the specified value has 8 digits, the first two hex digits are used as the alpha value. A value of "none" or "transparent" will not draw the shadow.
    viewportMarginIf set, this is the margin to place around the outside of all the pages displayed in the viewport, in pixels. The default value is 4.
    viewportGapIf set, this is the gap to place between multiple pages displayed in the viewport, in pixels (if applicable to the type of viewport in use). The default value is 10.
    printDialogThis can be set to native to always use the native print dialog, java to always use the Java dialog, or auto to choose depending on which print options are set. The native dialog does not allow options (such as number of copies, duplex printing) to be initialized, and some PDFs can specify defaults for these with the setOption mechanism. And the alternative java dialog may miss some advanced options, such as options for stapling the printed document. So a value of auto will use the native dialog unless the PDF (or the call to print specifies initial value for some of these options.

    This code is copyright the Big Faceless Organization. You're welcome to use, modify and distribute it in any form in your own projects, provided those projects continue to make use of the Big Faceless PDF library.

    Since:
    2.8
    See Also:
    Serialized Form

    • Constructor Detail

      • DocumentPanel

        public DocumentPanel()
        Create a new DocumentPanel

    • Method Detail

      • getJSManager

        public JSManager getJSManager()
        Return the JSManager object for this DocumentPanel.
        Since:
        2.9

      • setJSManager

        public void setJSManager​(JSManager jsmanager)
        Set the JSManager object for this DocumentPanel. This method should only be called if multiple DocumentPanel object are used in the same non-PDFViewer container.
        Since:
        2.9

      • getViewer

        public PDFViewer getViewer()
        Return the PDFViewer that contains this DocumentPanel. Note a DocumentPanel does not have to be contained inside a PDFViewer, in which case this method will return null.

      • setSidePanelSize

        public void setSidePanelSize​(int threshold,
                             int preferred)
        Control the size of the leftmost pane. The two values specify the threshold below which the pane is considered to be closed, and the default size of the pane when it's opened.
        Parameters:
        threshold - the minimum size, below which the panel is assumed to be closed
        preferred - the default size of the leftmost pane when opened

      • addSidePanelFactory

        public void addSidePanelFactory​(SidePanelFactory panelfactory)
        Add a SidePanelFactory to this DocumentPanel. When a PDF is set, the panels that are appropriate for that PDF will be created from this list of factories.
        Parameters:
        panelfactory - the factory

      • addAnnotationComponentFactory

        public void addAnnotationComponentFactory​(AnnotationComponentFactory annotationfactory)
        Add a AnnotationComponentFactory to this DocumentPanel. Any PDF's displayed by this panel will have annotations created by these factories.
        Parameters:
        annotationfactory - the factory

      • runAction

        public boolean runAction​(PDFAction action)
        Run the specified action on the PDF. Actions are handled by ActionHandlers, which should be registered with this class via the addActionHandler() method.
        Parameters:
        action - the PDFAction to run.
        Returns:
        true if the action was recognised and run successfully, false otherwise.

      • getDocumentPanelListeners

        public DocumentPanelListener[] getDocumentPanelListeners()
        Return a list of all the DocumentPanelListener objects registered on this DocumentPanel, or an empty array if there are none
        Returns:
        the list of listeners
        Since:
        2.13.1

      • raiseDocumentPanelEvent

        public void raiseDocumentPanelEvent​(DocumentPanelEvent event)
        Raise a DocumentPanelEvent on the DocumentPanel. In general this shouldn't be called unless you're extending one of the code classes, i.e. by writing your own DocumentViewport.
        Since:
        2.11.25

      • getSidePanels

        public Collection<SidePanel> getSidePanels()
        Return a read-only collection containing the SidePanel objects in use by this DocumentPanel.
        Since:
        2.10.3 (prior to this release a Map was returned instead)

      • removeSidePanel

        public void removeSidePanel​(SidePanel panel)
        Remove the specified SidePanel from the DocumentPanel.
        Since:
        2.10.3

      • addSidePanel

        public void addSidePanel​(SidePanel panel)
        Add the specified sidepanel to the DocumentPanel
        Since:
        2.10.3

      • setSelectedSidePanel

        public void setSelectedSidePanel​(SidePanel panel)
        Set the currently displayed SidePanel. If the specified SidePanel is not in the list of SidePanels added to this DocumentPanel, this method does nothing.
        Parameters:
        panel - the SidePanel to display, or null to display no SidePanel
        Since:
        2.10.3 (prior to this release the name of the panel was specified instead)

      • getSelectedSidePanel

        public SidePanel getSelectedSidePanel()
        Return the currently selected SidePanel, or null if no panels are displayed.
        Since:
        2.10.3 (prior to this release the name of the panel was returned instead)

      • setPDF

        public void setPDF​(PDF pdf)
        Set the PDF to be displayed by this DocumentPanel. A value of null will remove the current PDF from this object and free any resources that reference it - this should be done before this object is disposed of.
        Parameters:
        pdf - the PDF, or null to remove the current PDF

      • setPDF

        public void setPDF​(PDF pdf,
                   PDFPage page)
        Set the PDF to be displayed by this DocumentPanel, and specify the initial page to display.
        Parameters:
        pdf - the PDF, or null to remove the current PDF
        page - the initial page to display, or null to not display an initial page (exactly how this is handled depends on the Viewport). This will be ignored if the DocumentPanel is part of a PDFViewer and the PDF has an open action that sets the page.
        Since:
        2.11

      • setPDF

        public void setPDF​(PDFParser parser,
                   PDFPage page)
        Set the PDF to be displayed by this DocumentPanel, and specify the initial page to display and the exact PDFParser to use.
        Parameters:
        parser - the PDFParser to use to retrieve the PDF from
        page - the initial page to display, or null to not display an initial page (exactly how this is handled depends on the Viewport). This will be ignored if the DocumentPanel is part of a PDFViewer and the PDF has an open action that sets the page.
        Since:
        2.11.3

      • getParser

        public PDFParser getParser()
        Get the PDFParser being used to parse this PDF.

      • getAllParsers

        public List<PDFParser> getAllParsers()
        Return a read-only list of all PDFParser objects used in this DocumentPanel. Typically this will be a list of one item, the value returned from getParser()
        Since:
        2.26

      • getAllPDFs

        public List<PDF> getAllPDFs()
        Return a read-only list of all PDF objects used in this DocumentPanel. Typically this will be a list of one item, the value returned from getPDF()
        Since:
        2.26

      • getPDF

        public PDF getPDF()
        Return the PDF currently being displayed by this DocumentPanel

      • getPage

        public PDFPage getPage()
        Return the PDFPage currently being displayed by the DocumentViewport. If no PDF is set or the first page is still being rendered, this method will return null.

      • getNumberOfPages

        public int getNumberOfPages()
        Return the number of pages being displayed by the DocumentPanel. The same as getPDF().getNumberOfPages()
        Since:
        2.26

      • getPage

        public PDFPage getPage​(int i)
        Return the specified page being displayed by the DocumentPanel. The same as getPDF().getPage(i)
        Parameters:
        i - the page index, from 0..getNumberOfPages()
        Since:
        2.26

      • getPageNumber

        public int getPageNumber​(PDFPage page)
        Return the index (from 0) of the specified page in this DocumentPanel's pagelist, or -1 if it doesn't exist..
        Parameters:
        page - the page
        Since:
        2.26

      • getParser

        public PDFParser getParser​(PDFPage page)
        Return the PDFParser used for the specified page. The same as getParser()
        Since:
        2.26

      • getPageExtractor

        public PageExtractor getPageExtractor​(PDFPage page)
        Return the PageExtractor used for the specified page.
        Since:
        2.26

      • getPageLabels

        public List<String> getPageLabels()
        Return the list of PageLabels to use for all the pages in this DocumentPanel.
        Returns:
        a list of Strings to use as pagelabels. The list is getNumberOfPages() long
        Since:
        2.26

      • getLinearizedSupport

        public LinearizedSupport getLinearizedSupport()
        Return the LinearizedSupport object for this DocumentPanel
        Since:
        2.14.1

      • setPageNumber

        public void setPageNumber​(int i)
        Set the page being displayed. A shortcut for setPage(getPDF().getPage(i)).

      • getPageNumber

        public int getPageNumber()
        Return the pagenumber of the currently displayed page starting at 0, or -1 if no page is being displayed.

      • getZoom

        public float getZoom()
        Return the current zoom level. A value of 1 means the document is being displayed at it's actual size, 0.5 means 50% and so on.

      • setZoom

        public void setZoom​(float zoom)
        Set the current zoom level
        Parameters:
        zoom - the zoom level

      • setPage

        public void setPage​(PDFPage page)
        Set the page to display in the DocumentViewport. The page is displayed at it's top-left and at the current zoom level.
        Parameters:
        page - the page

      • redraw

        @Deprecated
public void redraw​(Object o)
        Deprecated.
        DocumentPanel.redraw() is no longer required as this object now listens to PropertyChangeEvents fired by the PDF. This method is not called anywhere and is a no-op
        Redraw the specified object. param o the Object that has been altered - typically a PDFPage or PDFAnnotation

      • setDirty

        public void setDirty​(boolean dirty)
        Set the document as being "dirty", ie that it has been modified since loading. The property noDirtyDocuments can be set to prevent this value from being set.
        Since:
        2.11.19

      • getWindowTitle

        public String getWindowTitle()
        Get the base title of the window containing this DocumentPanel, which does not include any "*" or loading progress details.
        Since:
        2.15.4

      • setWindowTitle

        public void setWindowTitle​(String title)
        Set the base title of the window containing this DocumentPanel
        Parameters:
        title - the new title.
        Since:
        2.15.4

      • isDirty

        public boolean isDirty()
        Return the value of the dirty flag, as set by setDirty(boolean)
        Since:
        2.11.19

      • fireUndoableEditEvent

        public void fireUndoableEditEvent​(UndoableEditEvent e)
        Fire an UndoableEditEvent on this DocumentPanel. As a special hack, passing new UndoableEditEvent(documentPanel, Undo.DISCARD) to this method will truncate the list of events
        Since:
        2.11.19

      • print

        public void print​(PrintService fservice,
                  PrintRequestAttributeSet fatts)
           throws PrintException,
                  PrinterException
        Display a Print dialog for printing this document, or if a PrintService is specified, print directly to that service without displaying a dialog.
        Parameters:
        fservice - the PrintService to print to. If this value is null a dialog will be displayed allowing the selection of a service.
        fatts - the print attributes - may be set to an AttributeSet to control the printing, or null to use the default.
        Throws:
        PrintException
        PrinterException

      • setSignaturePermissionRestrictions

        public void setSignaturePermissionRestrictions​(FormSignature sig)
        Limit the permissions that can be set on this PDF to ensure they don't conflict with the certification of this signature. This can be used to ensure that modifications to a PDF don't invalidate an existing digital siganture that disallows them. By default this is not the case, but setting the respectSignatureCertification initialization-parameter will ensure those restrictions are respected. This method can be called with null to make the setting of permissions unrestricted.
        Since:
        2.13
        See Also:
        hasPermission(java.lang.String), FormSignature.getCertificationType()

      • setAssociatedFile

        public void setAssociatedFile​(File file,
                              boolean enableSave)
        Set the associated File on this DocumentPanel. The file is the filename which the PDF is assumed to have originated - typically it is set automatically, but if the PDF was loaded into the viewer manually this method may be called later to update the filename
        Parameters:
        file - the file
        enableSave - if true, the file was loaded from this source, and the "Save" option should enabled. If false, the file serves as an initial filename only (for instance, if the file was loaded from a URL, or a bitmap image).
        Since:
        2.24.3

      • setAssociatedFile

        public void setAssociatedFile​(File file)
        Set the associated File on this DocumentPanel. Calls setAssociatedFile(file, true)
        Parameters:
        file - the file
        Since:
        2.18.1

      • getAssociatedFile

        public File getAssociatedFile()
        Get the associated File from this DocumentPanel. This is typically set automatically if the PDF was loaded via an Importer, but may not be set if the PDFViewer.loadPDF(java.io.File) method was used instead. The setAssociatedFile(java.io.File, boolean) method can be called to set it in that case.
        Returns:
        file the file associated with this DocumentPanel, which may be null if it hasn't been set.
        Since:
        2.18.1

      • getAssociatedFileEnablesSave

        public boolean getAssociatedFileEnablesSave()
        Return true if the associated file was loaded as an "import".
        Since:
        2.24.3

      • schedule

        public ScheduledFuture<?> schedule​(Runnable r,
                                   long delay)
        Schedule a timer task to run which is related to this DocmentPanel. The advantage of using this method over a standalone own timer is that all these tasks will be automatically cancelled when the DocumentPanel pdf is changed.
        Parameters:
        r - the runnable task to run
        delay - the delay in ms from now to run the task
        Returns:
        a ScheduledFuture which can be used to cancel the task
        Since:
        2.20.4

      • focus

        public void focus()
        Make this DocumentPanel the active one in any parent PDFViewer
        Since:
        2.26