From fcc0e7397bb6f3ceb1fe143667f8c59b5bf63874 Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Sat, 4 Jan 2014 17:15:04 +0100
Subject: Bug 935: NEWT PointerIcon: Refine Spec and Implementation / Fix OSX
 Crash and Issues

- Refine Display.PointerIcon: Complete type allowing re-creation
  - Add associated Display reference
  - Add used IOUtil.ClassResources reference
  - Add isValid()/validate() methods for recreation
  - Refine API doc

- Move Display.destroyPointerIcon(PointerIcon) -> PointerIcon.destroy()

- Move DisplayImpl.PointerIconImpl -> PointerIconImpl (own source file)

- Creation/Destruction and setting of PointerIcon happens on EDT

- DisplayImpl.shutdownAll() and Display.destroy() calls destroyAllPointerIconFromList

- WindowDriver.setPointerIconImpl: Validates PointerIconImpl (i.e. re-creates if required)

- Fix 'initial' window.setPointerIcon(..) before createNative(..),
  tested w/ TestGearsES2NEWT

- OSX Native Code:
  - Move mouse and pointer-state handling from NewtMacWindow -> NewtView class
    to retain states (pointer handle, pointer visibility, etc) when reparenting.
    Reparenting will move an exisiting NewtView into a new NewtMacWindow.

  - Enable all mouse move events:
    - NewtView::mouseEnter [nsWin makeFirstResponder: nsView];
    - NewtView::mouseExited if( !mouseConfined ) { [nsView resignFirstResponder]; }

  - NewtView::mouseMoved issued [myCurser set] if required, fixing
    OSX issue not updating NSCursor properly.

 - MacWindow:
    - Test NewtMacWindow, NewtView and NSCursor handles before usage
    - Fix DBG_PRINT(..) warnings
---
 src/newt/classes/com/jogamp/newt/Display.java | 67 +++++++++++++++++++++------
 1 file changed, 53 insertions(+), 14 deletions(-)

(limited to 'src/newt/classes/com')

diff --git a/src/newt/classes/com/jogamp/newt/Display.java b/src/newt/classes/com/jogamp/newt/Display.java
index cf1099c85..8d1445f80 100644
--- a/src/newt/classes/com/jogamp/newt/Display.java
+++ b/src/newt/classes/com/jogamp/newt/Display.java
@@ -66,16 +66,60 @@ public abstract class Display {
     /**
      * Native PointerIcon handle.
      * <p>
-     * Instances can be created via {@link Display#createPointerIcon(com.jogamp.common.util.IOUtil.ClassResources, int, int)}
-     * and released via {@link Display#destroyPointerIcon(PointerIcon)}.
+     * Instances can be created via {@link Display}'s {@link Display#createPointerIcon(com.jogamp.common.util.IOUtil.ClassResources, int, int) createPointerIcon(..)}.
+     * </p>
+     * <p>
+     * Instance is {@link #destroy()}'ed automatically if it's {@link #getDisplay() associated Display} is destroyed.
+     * </p>
+     * <p>
+     * Instance can be re-validated after destruction via {@link #validate()}.
+     * </p>
+     * <p>
+     * {@link PointerIcon} may be {@link #destroy() destroyed} manually after use,
+     * i.e. when no {@link Window} {@link Window#setPointerIcon(PointerIcon) uses them} anymore.
      * </p>
      * <p>
      * PointerIcons can be used via {@link Window#setPointerIcon(PointerIcon)}.
      * </p>
      */
     public static interface PointerIcon {
+        /**
+         * @return the associated Display
+         */
+        Display getDisplay();
+
+        /**
+         * @return the single {@link IOUtil.ClassResources}.
+         */
+        IOUtil.ClassResources getResource();
+
+        /**
+         * Returns true if valid, otherwise false.
+         * <p>
+         * A PointerIcon instance becomes invalid if it's {@link #getDisplay() associated Display} is destroyed.
+         * </p>
+         */
+        boolean isValid();
+
+        /**
+         * Returns true if instance {@link #isValid()} or validation was successful, otherwise false.
+         * <p>
+         * Validation, i.e. recreation, is required if instance became invalid, see {@link #isValid()}.
+         * </p>
+         */
+        boolean validate();
+
+        /**
+         * Destroys this instance.
+         * <p>
+         * Will be called automatically if it's {@link #getDisplay() associated Display} is destroyed.
+         * </p>
+         */
+        void destroy();
+
         /** Returns the size, i.e. width and height. */
         DimensionImmutable getSize();
+
         /** Returns the hotspot. */
         PointImmutable getHotspot();
 
@@ -84,28 +128,23 @@ public abstract class Display {
     }
 
     /**
-     * Returns the created {@link PointerIcon} or <code>null</code> if not implemented on platform.
+     * Returns the newly created {@link PointerIcon} or <code>null</code> if not implemented on platform.
+     * <p>
+     * See {@link PointerIcon} for lifecycle semantics.
+     * </p>
      *
-     * @param pngResource PNG resource
+     * @param pngResource single PNG resource, only the first entry of {@link IOUtil.ClassResources#resourcePaths} is used.
      * @param hotX pointer hotspot x-coord, origin is upper-left corner
      * @param hotY pointer hotspot y-coord, origin is upper-left corner
+     * @throws IllegalStateException if this Display instance is not {@link #isNativeValid() valid yet}.
      * @throws MalformedURLException
      * @throws InterruptedException
      * @throws IOException
      *
      * @see PointerIcon
-     * @see #destroyPointerIcon(PointerIcon)
      * @see Window#setPointerIcon(PointerIcon)
      */
-
-    public abstract PointerIcon createPointerIcon(final IOUtil.ClassResources pngResource, final int hotX, final int hotY) throws MalformedURLException, InterruptedException, IOException;
-
-    /**
-     * @param pi
-     *
-     * @see #createPointerIcon(com.jogamp.common.util.IOUtil.ClassResources, int, int)
-     */
-    public abstract void destroyPointerIcon(PointerIcon pi);
+    public abstract PointerIcon createPointerIcon(final IOUtil.ClassResources pngResource, final int hotX, final int hotY) throws IllegalStateException, MalformedURLException, InterruptedException, IOException;
 
     /**
      * Manual trigger the native creation, if it is not done yet.<br>
-- 
cgit v1.2.3