Bug 1142 - NEWT: Add support to retrieve the primary MonitorDevice

Support added for
  - Windows
  - X11 XRandR 1.3
  - OSX

Note: Our whole MonitorMode association handling is currently _not_ dynamic.
 - only on Windows we actually use native unique ID,
   which might not change (adapter and monitor idx)

 - On OSX and X11 we simply use indices,
   but if monitor setup changes - they refer to different instances.

In case it is desired to cover dynamic monitor setup change,
we need to address this issue in a new bug entry.

2 files changed, 42 insertions, 7 deletions

diff --git a/src/newt/classes/com/jogamp/newt/MonitorDevice.java b/src/newt/classes/com/jogamp/newt/MonitorDevice.java
index ec38ce3c3..88f8376c7 100644
--- a/src/newt/classes/com/jogamp/newt/MonitorDevice.java
+++ b/src/newt/classes/com/jogamp/newt/MonitorDevice.java
@@ -68,6 +68,7 @@ public abstract class MonitorDevice {
     protected final Rectangle viewportPU; // in pixel units
     protected final Rectangle viewportWU; // in window units
     protected boolean isClone;
+    protected boolean isPrimary;
     protected MonitorMode currentMode;
     protected boolean modeChanged;
 
@@ -75,6 +76,7 @@ public abstract class MonitorDevice {
      * @param screen associated {@link Screen}
      * @param nativeId unique monitor device ID
      * @param isClone flag
+     * @param isPrimary flag
      * @param sizeMM size in millimeters
      * @param currentMode
      * @param pixelScale pre-fetched current pixel-scale, maybe {@code null} for {@link ScalableSurface#IDENTITY_PIXELSCALE}.
@@ -82,10 +84,10 @@ public abstract class MonitorDevice {
      * @param viewportWU viewport in window-units
      * @param supportedModes all supported {@link MonitorMode}s
      */
-    protected MonitorDevice(final Screen screen, final int nativeId, final boolean isClone,
-                            final DimensionImmutable sizeMM,
-                            final MonitorMode currentMode, final float[] pixelScale, final Rectangle viewportPU,
-                            final Rectangle viewportWU, final ArrayHashSet<MonitorMode> supportedModes) {
+    protected MonitorDevice(final Screen screen, final int nativeId,
+                            final boolean isClone, final boolean isPrimary,
+                            final DimensionImmutable sizeMM, final MonitorMode currentMode, final float[] pixelScale,
+                            final Rectangle viewportPU, final Rectangle viewportWU, final ArrayHashSet<MonitorMode> supportedModes) {
         this.screen = screen;
         this.nativeId = nativeId;
         this.sizeMM = sizeMM;
@@ -96,6 +98,7 @@ public abstract class MonitorDevice {
         this.viewportWU = viewportWU;
 
         this.isClone = isClone;
+        this.isPrimary = isPrimary;
         this.currentMode = currentMode;
         this.modeChanged = false;
     }
@@ -141,6 +144,12 @@ public abstract class MonitorDevice {
     public final boolean isClone() { return isClone; }
 
     /**
+     * Returns {@code true} if this device represents the <i>primary device</i>, otherwise return {@code false}.
+     * @see Screen#getPrimaryMonitor()
+     */
+    public final boolean isPrimary() { return isPrimary; }
+
+    /**
      * @return the immutable monitor size in millimeters.
      */
     public final DimensionImmutable getSizeMM() {
@@ -331,9 +340,28 @@ public abstract class MonitorDevice {
 
     @Override
     public String toString() {
-        return "Monitor[Id "+Display.toHexString(nativeId)+", clone "+isClone+", "+sizeMM+" mm, pixelScale ["+pixelScale[0]+", "+pixelScale[1]+
-               "], viewport "+viewportPU+ " [pixels], "+viewportWU+" [window], orig "+originalMode+", curr "+currentMode+
-               ", modeChanged "+modeChanged+", modeCount "+supportedModes.size()+"]";
+        boolean preComma = false;
+        final StringBuilder sb = new StringBuilder();
+        sb.append("Monitor[Id ").append(Display.toHexString(nativeId)).append(", options[");
+        {
+            if( isClone() ) {
+                sb.append("clone");
+                preComma = true;
+            }
+            if( isPrimary() ) {
+                if( preComma ) {
+                    sb.append(", ");
+                }
+                sb.append("primary");
+            }
+        }
+        preComma = false;
+        sb.append("], ").append(sizeMM).append(" mm, pixelScale [").append(pixelScale[0]).append(", ")
+        .append(pixelScale[1]).append("], viewport ").append(viewportPU).append(" [pixels], ").append(viewportWU)
+        .append(" [window], orig ").append(originalMode).append(", curr ")
+        .append(currentMode).append(", modeChanged ").append(modeChanged).append(", modeCount ")
+        .append(supportedModes.size()).append("]");
+        return sb.toString();
     }
 }
 
diff --git a/src/newt/classes/com/jogamp/newt/Screen.java b/src/newt/classes/com/jogamp/newt/Screen.java
index b8f096fc3..9b2a280f9 100644
--- a/src/newt/classes/com/jogamp/newt/Screen.java
+++ b/src/newt/classes/com/jogamp/newt/Screen.java
@@ -209,6 +209,13 @@ public abstract class Screen {
     public abstract List<MonitorDevice> getMonitorDevices();
 
     /**
+     * Returns the windowing manager's primary {@link MonitorDevice},
+     * which holds the system menu bar, etc.
+     * @see MonitorDevice#isPrimary()
+     */
+    public abstract MonitorDevice getPrimaryMonitor();
+
+    /**
      * Returns the {@link MonitorDevice} with the highest {@link MonitorDevice#getViewportInWindowUnits() viewport}
      * {@link RectangleImmutable#coverage(RectangleImmutable) coverage} of the given rectangle in window units,
      * which is not a {@link MonitorDevice#isClone() clone}.