PreviewPanel (Apache FOP Core 2.11 API)
Date: 2025-04-24

org.apache.fop.render.awt.viewer

## Class PreviewPanel

- java.lang.Object
- - java.awt.Component
  - - java.awt.Container
    - - javax.swing.JComponent
      - - javax.swing.JPanel
        - - org.apache.fop.render.awt.viewer.PreviewPanel

- All Implemented Interfaces:
    ImageObserver, MenuContainer, Serializable, Accessible

      public class PreviewPanel
      extends JPanel

  Holds a scrollpane with the rendered page(s) and handles actions performed to alter the display of the page.

  Use PreviewPanel when you want to embed a preview in your own application with your own controls. Use PreviewDialog when you want to use the standard Fop controls.

  In order to embed a PreviewPanel in your own app, create your own renderer, and your own agent. In order to support reloads, you may also implement your own Renderable extension or the default InputHandler. Setting the Renderable to null works fine though. Then call setPreviewDialogDisplayed(false) to hide the default dialog. Finally create a preview panel with the agent, renderable and renderer and add it to your gui:

       FopFactory fopFactory = FopFactory.newInstance();
       FOUserAgent agent = fopFactory.newFOUserAgent();
       AWTRenderer renderer = new AWTRenderer(agent);
       agent.setRendererOverride(renderer);
       previewPanel = new PreviewPanel(agent, null, renderer);
       previewPanel = new PreviewPanel(ua);
       myGui.add(previewPanel);

  In order to set options and display a page do:

       renderer.clearViewportList();
       // build report xml here
       reload(); // optional if setting changed

  If you wan't to change settings, don't call reload. A good example is to set the page to fill the screen and set the scrolling mode:

       double scale = previewPanel.getScaleToFitWindow();
       previewPanel.setScaleFactor(scale);
       previewPanel.setDisplayMode(PreviewPanel.CONTINUOUS);

  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class javax.swing.JPanel

      `JPanel.AccessibleJPanel`

    - ### Nested classes/interfaces inherited from class javax.swing.JComponent

      `JComponent.AccessibleJComponent`

    - ### Nested classes/interfaces inherited from class java.awt.Container

      `Container.AccessibleAWTContainer`

    - ### Nested classes/interfaces inherited from class java.awt.Component

      `Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `CONT_FACING` Constant for displaying even/odd pages side by side in continuous form.
    `static int` | `CONTINUOUS` Constant for setting continuous page display.
    `protected FOUserAgent` | `foUserAgent` The FOUserAgent associated with this panel - often shared with PreviewDialog
    `protected Renderable` | `renderable` Renderable instance that can be used to reload and re-render a document after modifications.
    `static int` | `SINGLE` Constant for setting single page display.

    - ### Fields inherited from class javax.swing.JComponent

      `listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW`

    - ### Fields inherited from class java.awt.Component

      `accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT`

    - ### Fields inherited from interface java.awt.image.ImageObserver

      `ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PreviewPanel(FOUserAgent foUserAgent, Renderable renderable, AWTRenderer renderer)` Creates a new PreviewPanel instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addPageChangeListener(PageChangeListener l)` Add a listener to receive notification of page change events.
    `protected void` | `firePageChange(int oldPage, int newPage)` Notify all registered listeners of a page change event.
    `int` | `getDisplayMode()` Returns the display mode.
    `int` | `getPage()`
    `double` | `getScaleToFit(double viewWidth, double viewHeight)` Returns the scale factor required in order to fit either the current page or two adjacent pages within a window of the given height and width, depending on the display mode.
    `double` | `getScaleToFitWidth()` As getScaleToFitWindow, but ignoring the Y axis.
    `double` | `getScaleToFitWindow()` Returns the scale factor required in order to fit either the current page within the current window or to fit two adjacent pages within the display if the displaymode is continuous.
    `void` | `reload()` Reloads and reformats document.
    `void` | `removePageChangeListener(PageChangeListener l)` Removes a page change listener.
    `void` | `setDisplayMode(int mode)` Sets the display mode.
    `void` | `setPage(int number)` Selects the given page, displays it on screen and notifies listeners about the change in selection.
    `void` | `setScaleFactor(double scale)` Scales page image
    `void` | `showPage()` Starts rendering process and shows the current page.

    - ### Methods inherited from class javax.swing.JPanel

      `getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI`

    - ### Methods inherited from class javax.swing.JComponent

      `addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update`

    - ### Methods inherited from class java.awt.Container

      `add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree`

    - ### Methods inherited from class java.awt.Component

      `action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### SINGLE

          public static final int SINGLE

      Constant for setting single page display.
      See Also:
        Constant Field Values

    - #### CONTINUOUS

          public static final int CONTINUOUS

      Constant for setting continuous page display.
      See Also:
        Constant Field Values

    - #### CONT_FACING

          public static final int CONT_FACING

      Constant for displaying even/odd pages side by side in continuous form.
      See Also:
        Constant Field Values

    - #### foUserAgent

          protected FOUserAgent foUserAgent

      The FOUserAgent associated with this panel - often shared with PreviewDialog

    - #### renderable

          protected Renderable renderable

      Renderable instance that can be used to reload and re-render a document after modifications.

  - ### Constructor Detail

    - #### PreviewPanel

          public PreviewPanel(FOUserAgent foUserAgent,
                              Renderable renderable,
                              AWTRenderer renderer)

      Creates a new PreviewPanel instance.
      Parameters:
        `foUserAgent` - the user agent
        `renderable` - the Renderable instance that is used to reload/re-render a document after modifications.
        `renderer` - the AWT Renderer instance to paint with

  - ### Method Detail

    - #### getPage

          public int getPage()

      Returns:
        the currently visible page

    - #### setPage

          public void setPage(int number)

      Selects the given page, displays it on screen and notifies listeners about the change in selection.
      Parameters:
        `number` - the page number

    - #### setDisplayMode

          public void setDisplayMode(int mode)

      Sets the display mode.
      Parameters:
        `mode` - One of SINGLE, CONTINUOUS or CONT_FACING.

    - #### getDisplayMode

          public int getDisplayMode()

      Returns the display mode.
      Returns:
        mode One of SINGLE, CONTINUOUS or CONT_FACING.

    - #### reload

          public void reload()

      Reloads and reformats document.

    - #### addPageChangeListener

          public void addPageChangeListener(PageChangeListener l)

      Add a listener to receive notification of page change events. Events will be fired whenever the currentPage value is changed. The values recorded are 0-based.
      Parameters:
        `l` - the page change listener to add

    - #### removePageChangeListener

          public void removePageChangeListener(PageChangeListener l)

      Removes a page change listener.
      Parameters:
        `l` - the page change listener to remove

    - #### firePageChange

          protected void firePageChange(int oldPage,
                                        int newPage)

      Notify all registered listeners of a page change event.
      Parameters:
        `oldPage` - the old page
        `newPage` - the new page

    - #### setScaleFactor

          public void setScaleFactor(double scale)

      Scales page image
      Parameters:
        `scale` - [0;1]

    - #### getScaleToFitWindow

          public double getScaleToFitWindow()
                                     throws FOPException

      Returns the scale factor required in order to fit either the current page within the current window or to fit two adjacent pages within the display if the displaymode is continuous.
      Returns:
        the requested scale factor
      Throws:
        `FOPException` - in case of an error while fetching the PageViewport

    - #### getScaleToFitWidth

          public double getScaleToFitWidth()
                                    throws FOPException

      As getScaleToFitWindow, but ignoring the Y axis.
      Returns:
        the requested scale factor
      Throws:
        `FOPException` - in case of an error while fetching the PageViewport

    - #### getScaleToFit

          public double getScaleToFit(double viewWidth,
                                      double viewHeight)
                               throws FOPException

      Returns the scale factor required in order to fit either the current page or two adjacent pages within a window of the given height and width, depending on the display mode. In order to ignore either dimension, just specify it as Double.MAX_VALUE.
      Parameters:
        `viewWidth` - width of the view
        `viewHeight` - height of the view
      Returns:
        the requested scale factor
      Throws:
        `FOPException` - in case of an error while fetching the PageViewport

    - #### showPage

          public void showPage()

      Starts rendering process and shows the current page.

Copyright © 2025 Apache Software Foundation. All rights reserved.