Bugzilla: #35358

Fixed the following:
Dialog appearing when panel embedded in custom apps.
NullPointerExceptions when embedding PreviewPanel.
PreviewPanel docs inaccurate.
Submitted by:	Richard Wheeldon <richardw.at.geoquip-rnd.demon.co.uk>


git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@198753 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 91 insertions, 21 deletions

diff --git a/src/java/org/apache/fop/render/awt/AWTRenderer.java b/src/java/org/apache/fop/render/awt/AWTRenderer.java
index 4c65205f0..d6c2a1a3c 100644
--- a/src/java/org/apache/fop/render/awt/AWTRenderer.java
+++ b/src/java/org/apache/fop/render/awt/AWTRenderer.java
@@ -67,39 +67,64 @@ public class AWTRenderer extends Java2DRenderer implements Pageable, Printable {
     /** flag for debugging */
     public boolean debug;
 
+    /** If true, preview dialog is shown. */
+    public boolean dialogDisplay = true;
+
     /**
      * The preview dialog frame used for display of the documents. Also used as
      * the AWT Component for FontSetup in generating valid font measures.
      */
     protected PreviewDialog frame;
 
+    /**
+     * Creates a new AWTRenderer instance.
+     */
     public AWTRenderer() {
         translator = new Translator();
     }
 
+    /** @see org.apache.fop.render.Renderer#setUserAgent(org.apache.fop.apps.FOUserAgent) */
     public void setUserAgent(FOUserAgent foUserAgent) {
         super.setUserAgent(foUserAgent);
-        createPreviewDialog();
+        if (dialogDisplay) {
+            createPreviewDialog();
+        }
+    }
+
+    /**
+     * Sets whether the preview dialog should be created and displayed when
+     * the rendering is finished.
+     * @param show If false, preview dialog is not shown. True by default
+     */
+    public void setPreviewDialogDisplayed(boolean show) {
+        dialogDisplay = show;
     }
 
+    /** @see org.apache.fop.render.Renderer#renderPage(org.apache.fop.area.PageViewport) */
     public void renderPage(PageViewport pageViewport) 
             throws IOException, FOPException {
 
         super.renderPage(pageViewport);
-        frame.setInfo();
+        if (frame != null) {
+            frame.setInfo();
+        }
     }
 
+    /** @see org.apache.fop.render.Renderer#stopRenderer() */
     public void stopRenderer() throws IOException {
         super.stopRenderer();
-        frame.setStatus(translator.getString("Status.Show"));
+        if (frame != null) {
+            frame.setStatus(translator.getString("Status.Show"));
             frame.reload(); // Refreshes view of page
         }
+    }
 
-        /**
-         * Returns the dimensions of the specified page
-         * @exception FOPException If the page is out of range or has not been rendered.
-         */
-        public Dimension getPageImageSize(int pageNum) throws FOPException {
+    /**
+     * @return the dimensions of the specified page
+     * @param pageNum the page number
+     * @exception FOPException If the page is out of range or has not been rendered.
+     */
+    public Dimension getPageImageSize(int pageNum) throws FOPException {
         Rectangle2D bounds = getPageViewport(pageNum).getViewArea();
         pageWidth = (int) Math.round(bounds.getWidth() / 1000f);
         pageHeight = (int) Math.round(bounds.getHeight() / 1000f);
diff --git a/src/java/org/apache/fop/render/awt/viewer/ImageProxyPanel.java b/src/java/org/apache/fop/render/awt/viewer/ImageProxyPanel.java
index a3946fbdc..89cb27feb 100644
--- a/src/java/org/apache/fop/render/awt/viewer/ImageProxyPanel.java
+++ b/src/java/org/apache/fop/render/awt/viewer/ImageProxyPanel.java
@@ -54,21 +54,26 @@ public class ImageProxyPanel extends JPanel {
 
     /**
      * Panel constructor. Doesn't allocate anything until needed.
+     * @param renderer the AWTRenderer instance to use for painting
+     * @param page initial page number to show
      */
     public ImageProxyPanel(AWTRenderer renderer, int page) {
         this.renderer = renderer;
         this.page = page;
+        // Allows single panel to appear behind page display.
+        // Important for textured L&Fs.
+        setOpaque(false);
     }
 
     /**
-     * Returns the size of the page plus the border.
+     * @return the size of the page plus the border.
      */
     public Dimension getMinimumSize() {
         return getPreferredSize();
     }
 
     /**
-     * Returns the size of the page plus the border.
+     * @return the size of the page plus the border.
      */
     public Dimension getPreferredSize() {
         if (size == null) {
@@ -87,6 +92,7 @@ public class ImageProxyPanel extends JPanel {
 
     /**
      * Sets the number of the page to be displayed and refreshes the display.
+     * @param pg the page number
      */
     public void setPage(int pg) {
         if (page != pg) {
diff --git a/src/java/org/apache/fop/render/awt/viewer/PreviewPanel.java b/src/java/org/apache/fop/render/awt/viewer/PreviewPanel.java
index 30becc657..bc63c14a9 100644
--- a/src/java/org/apache/fop/render/awt/viewer/PreviewPanel.java
+++ b/src/java/org/apache/fop/render/awt/viewer/PreviewPanel.java
@@ -42,18 +42,42 @@ import org.apache.fop.render.awt.AWTRenderer;
 
 
 /**
- * Holds a scrollpane with the rendered page(s) and handles actions performed
+ * <p>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
+ * </p>
+ * <p>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, use the following:
+ * </p>   
+ * <p>In order to embed a PreviewPanel in your own app, create your own renderer,
+ * and your own agent. Then call setPreviewDialogDisplayed(false) to hide the
+ * default dialog. Finally create a preview panel with the renderer and add it
+ * to your gui:
+ * </p>
  * <pre>
- * FOUserAgent ua = new FOUserAgent();
- * ua.setRendererOverride(new AWTRenderer());
+ * AWTRenderer renderer = new AWTRenderer();
+ * FOUserAgent agent = new FOUserAgent();
+ * agent.setRendererOverride(renderer);
+ * renderer.setPreviewDialogDisplayed(false);
+ * renderer.setUserAgent(agent);
+ * previewPanel = new PreviewPanel(agent, renderer);
  * previewPanel = new PreviewPanel(ua);
+ * myGui.add(previewPanel);
+ * </pre>
+ *
+ * In order to set options and display a page do:
+ * <pre>
+ * renderer.clearViewportList();
+ * // build report xml here
+ * reload(); // optional if setting changed
+ * </pre>
+ *
+ * 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:
+ * <pre>
+ * double scale = previewPanel.getScaleToFitWindow();
+ * previewPanel.setScaleFactor(scale);
+ * previewPanel.setDisplayMode(PreviewPanel.CONTINUOUS);
  * </pre>
  */
 public class PreviewPanel extends JPanel {
@@ -109,6 +133,11 @@ public class PreviewPanel extends JPanel {
     private ViewportScroller scroller;
 
         
+    /**
+     * Creates a new PreviewPanel instance.
+     * @param foUserAgent the user agent
+     * @param renderer the AWT Renderer instance to paint with
+     */
     public PreviewPanel(FOUserAgent foUserAgent, AWTRenderer renderer) {
         super(new GridLayout(1, 1));
         this.renderer = renderer;
@@ -296,15 +325,17 @@ public class PreviewPanel extends JPanel {
                 gridPanel.add(pagePanels[pg]);
             }
 
-            renderer.clearViewportList();
-
             try {
-                foUserAgent.getInputHandler().render(fop);
-                setPage(savedCurrentPage);
+                if (foUserAgent.getInputHandler() != null) {
+                    renderer.clearViewportList();
+                    foUserAgent.getInputHandler().render(fop);
+                }
             } catch (FOPException e) {
                 e.printStackTrace();
                 // FIXME Should show exception in gui - was reportException(e);
             }
+
+            setPage(savedCurrentPage);
         }
     }
 
@@ -321,6 +352,8 @@ public class PreviewPanel extends JPanel {
      * 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.
+     * @return the requested scale factor
+     * @throws FOPException in case of an error while fetching the PageViewport
      */
     public double getScaleToFitWindow() throws FOPException {
         Dimension extents = previewArea.getViewport().getExtentSize();
@@ -330,6 +363,8 @@ public class PreviewPanel extends JPanel {
 
     /**
      * As getScaleToFitWindow, but ignoring the Y axis.
+     * @return the requested scale factor
+     * @throws FOPException in case of an error while fetching the PageViewport
      */
     public double getScaleToFitWidth() throws FOPException {
         Dimension extents = previewArea.getViewport().getExtentSize();
@@ -341,6 +376,10 @@ public class PreviewPanel extends JPanel {
      * 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.
+     * @param viewWidth width of the view
+     * @param viewHeight height of the view
+     * @return the requested scale factor
+     * @throws FOPException in case of an error while fetching the PageViewport
      */
     public double getScaleToFit(double viewWidth, double viewHeight) throws FOPException {
         PageViewport pageViewport = renderer.getPageViewport(currentPage);