From c654bf3605ff4dca6d8231c2fe8b4db8e6b22b4c Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Sun, 8 Sep 2013 12:32:56 +0200
Subject: AWTPrintLifecycle: Add detailed API doc

---
 .../javax/media/opengl/awt/AWTPrintLifecycle.java  | 63 +++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

diff --git a/src/jogl/classes/javax/media/opengl/awt/AWTPrintLifecycle.java b/src/jogl/classes/javax/media/opengl/awt/AWTPrintLifecycle.java
index 293bdb809..301e18722 100644
--- a/src/jogl/classes/javax/media/opengl/awt/AWTPrintLifecycle.java
+++ b/src/jogl/classes/javax/media/opengl/awt/AWTPrintLifecycle.java
@@ -38,11 +38,43 @@ import jogamp.nativewindow.awt.AWTMisc;
 /**
  * Interface describing print lifecycle to support AWT printing
  * on AWT {@link GLAutoDrawable}s.
+ * <a name="impl"><h5>Implementations</h5></a>
+ * <p>
+ * Implementing {@link GLAutoDrawable} classes based on AWT
+ * supporting {@link Component#print(Graphics)} shall implement this interface.
+ * </p>
+ * <a name="usage"><h5>Usage</h5></a>
+ * <p>
+ * Users attempting to print an AWT {@link Container} containing {@link AWTPrintLifecycle} elements
+ * shall consider decorating the {@link Container#printAll(Graphics)} call with<br>
+ * {@link #setupPrint(Graphics2D, double, double) setupPrint(..)} and {@link #releasePrint()}
+ * on all {@link AWTPrintLifecycle} elements in the {@link Container}.<br>
+ * To minimize this burden, a user can use {@link Context#setupPrint(Container, Graphics2D, double, double) Context.setupPrint(..)}:
+ * <pre>
+ *  Graphics2D g2d;
+ *  Frame frame;
+ *  double scaleGLMatXY = 72.0/glDPI;
+ *  ...
+    final AWTPrintLifecycle.Context ctx = AWTPrintLifecycle.Context.setupPrint(frame, g2d, scaleGLMatXY, scaleGLMatXY);
+    try {
+       AWTEDTExecutor.singleton.invoke(true, new Runnable() {
+            public void run() {
+                frame.printAll(g2d);
+           } });
+    } finally {
+       ctx.releasePrint();
+    }
+ * 
+ * </pre>
+ * </p>
  */
 public interface AWTPrintLifecycle {
 
     /**
      * Shall be called before {@link Component#print(Graphics)}.
+     * <p>
+     * See <a href="#usage">Usage</a>.
+     * </p>
      * @param g2d the {@link Graphics2D} instance, which will be used for printing.
      * @param scaleMatX {@link Graphics2D} {@link Graphics2D#scale(double, double) scaling factor}, i.e. rendering 1/scaleMatX * width pixels
      * @param scaleMatY {@link Graphics2D} {@link Graphics2D#scale(double, double) scaling factor}, i.e. rendering 1/scaleMatY * height pixels
@@ -51,20 +83,49 @@ public interface AWTPrintLifecycle {
     
     /**
      * Shall be called after very last {@link Component#print(Graphics)}.
+     * <p>
+     * See <a href="#usage">Usage</a>.
+     * </p>
      */
     void releasePrint();
 
+    /**
+     * Convenient {@link AWTPrintLifecycle} context simplifying calling {@link AWTPrintLifecycle#setupPrint(Graphics2D, double, double) setupPrint(..)}
+     * and {@link AWTPrintLifecycle#releasePrint()} on all {@link AWTPrintLifecycle} elements of a {@link Container}.
+     * <p>
+     * See <a href="#usage">Usage</a>.
+     * </p>
+     */
     public static class Context {
+        /**
+         * <p>
+         * See <a href="#usage">Usage</a>.
+         * </p>
+         * 
+         * @param c container to be traversed through to perform {@link AWTPrintLifecycle#setupPrint(Graphics2D, double, double) setupPrint(..)} on all {@link AWTPrintLifecycle} elements.
+         * @param g2d the {@link Graphics2D} instance, which will be used for printing.
+         * @param scaleMatX {@link Graphics2D} {@link Graphics2D#scale(double, double) scaling factor}, i.e. rendering 1/scaleMatX * width pixels
+         * @param scaleMatY {@link Graphics2D} {@link Graphics2D#scale(double, double) scaling factor}, i.e. rendering 1/scaleMatY * height pixels
+         * @return the context
+         */
         public static Context setupPrint(Container c, Graphics2D g2d, double scaleMatX, double scaleMatY) {
             final Context t = new Context(c, g2d, scaleMatX, scaleMatY);
             t.setupPrint(c);
             return t;
         }
 
+        /**
+         * <p>
+         * See <a href="#usage">Usage</a>.
+         * </p>
+         */
         public void releasePrint() {
             count = AWTMisc.performAction(cont, AWTPrintLifecycle.class, releaseAction);
         }
-        
+
+        /**
+         * @return count of performed actions of last {@link #setupPrint(Container, Graphics2D, double, double) setupPrint(..)} or {@link #releasePrint()}.
+         */
         public int getCount() { return count; }
         
         private final Container cont;
-- 
cgit v1.2.3