NativeWindow/NEWT: Cont. refinement of Insets usage

Completes commit d4670328991c02a6f11f8873ea7a2331f17d0ef0

3 files changed, 21 insertions, 9 deletions

diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
index 22e4b0f80..e691ba8e6 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
@@ -136,13 +136,13 @@ public interface NativeSurface extends SurfaceUpdatedListener {
   public long getSurfaceHandle();
 
   /**
-   * Returns the width of the client area.
+   * Returns the width of the client area excluding insets (window decorations).
    * @return width of the client area
    */
   public int getWidth();
 
   /**
-   * Returns the height of the client area.
+   * Returns the height of the client area excluding insets (window decorations).
    * @return height of the client area
    */
   public int getHeight();
diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java b/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
index 0f6f84f66..76ac72953 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
@@ -76,10 +76,14 @@ public interface NativeWindow extends NativeSurface {
   public long getWindowHandle();
 
   /** 
-   * Returns the insets defined as the difference between
-   * the top-level window with decorations and the client area.<br>
+   * Returns the insets defined as the width and height of the window decoration
+   * on the left, right, top and bottom.<br>
    * Insets are zero if the window is undecorated, including child windows.
    * 
+   * <p>
+   * Insets are available only after the native window has been created,
+   * ie. the native window has been made visible.<br>
+   *   
    * The top-level window area's top-left corner is located at
    * <pre>
    *   getX() - getInsets().{@link InsetsImmutable#getLeftWidth() getLeftWidth()}
@@ -100,14 +104,14 @@ public interface NativeWindow extends NativeSurface {
   
   /** 
    * @return the current x position of the top-left corner
-   *         of the client area, hence excluding decorations if enabled.<br> 
+   *         of the client area, hence excluding insets (window decorations).<br> 
    * @see #getInsets()
    */
   public int getX();
 
   /** 
    * @return the current y position of the top-left corner
-   *         of the client area, hence excluding decorations if enabled.<br> 
+   *         of the client area, hence excluding insets (window decorations).<br> 
    * @see #getInsets()
    */
   public int getY();
diff --git a/src/newt/classes/com/jogamp/newt/Window.java b/src/newt/classes/com/jogamp/newt/Window.java
index c8eb2b1f5..ed1cd93a9 100644
--- a/src/newt/classes/com/jogamp/newt/Window.java
+++ b/src/newt/classes/com/jogamp/newt/Window.java
@@ -179,8 +179,12 @@ public interface Window extends NativeWindow, WindowClosingProtocol {
     void setSize(int width, int height);
 
     /**
-     * Sets the size of the top-level window including decorations.
+     * Sets the size of the top-level window including insets (window decorations).
      * 
+     * <p>
+     * Note: Insets (if supported) are available only after the window is set visible and hence has been created.
+     * </p>
+     *
      * @param width of the top-level window area
      * @param height of the top-level window area
      * 
@@ -190,7 +194,7 @@ public interface Window extends NativeWindow, WindowClosingProtocol {
     void setTopLevelSize(int width, int height);
     
     /**
-     * Sets the location of the window's client area, excluding decorations.<br>
+     * Sets the location of the window's client area, excluding insets (window decorations).<br>
      * 
      * This call is ignored if in fullscreen mode.<br>
      *
@@ -202,7 +206,11 @@ public interface Window extends NativeWindow, WindowClosingProtocol {
     void setPosition(int x, int y);
     
     /**
-     * Sets the location of the top-level window inclusive decorations.<br>
+     * Sets the location of the top-level window inclusive insets (window decorations).<br>
+     * 
+     * <p>
+     * Note: Insets (if supported) are available only after the window is set visible and hence has been created.
+     * </p>
      * 
      * This call is ignored if in fullscreen mode.<br>
      *