com.jogamp.newt

## Class Screen

- java.lang.Object
- - com.jogamp.newt.Screen

-     public abstract class Screen
      extends Object

  A screen may span multiple `MonitorDevice`s representing their combined virtual size.

  All values of this interface are represented in pixel units, if not stated otherwise.

  ##### Coordinate System

  - Screen space has it's origin in the top-left corner, and may not be at 0/0.
  - `Virtual viewport` covers all `MonitorDevice`s `viewports` and has it's origin in the top-left corner, and may not be at 0/0.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DEBUG`
    `static int` | `SCREEN_MODE_CHANGE_TIMEOUT` A 10s timeout for screen mode change.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Screen()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `addMonitorModeListener(MonitorModeListener sml)`
    `abstract int` | `addReference()` See `Display.addReference()`
    `abstract void` | `createNative()` Manual trigger the native creation, if not done yet.. This is useful to be able to request the `AbstractGraphicsScreen`, via `getGraphicsScreen()`. Otherwise the abstract device won't be available before the dependent component (Window) is realized.
    `abstract void` | `destroy()` Manually trigger the destruction, incl.
    `boolean` | `equals(Object obj)` return true if obj is of type Display and both FQN `getFQName()` equals
    `static int` | `getActiveScreenNumber()`
    `static Collection<Screen>` | `getAllScreens()` Returns the global screen collection
    `abstract Display` | `getDisplay()`
    `static Screen` | `getFirstScreenOf(Display display, int idx, int fromIndex)`
    `abstract String` | `getFQName()`
    `abstract AbstractGraphicsScreen` | `getGraphicsScreen()`
    `abstract int` | `getHeight()`
    `abstract int` | `getIndex()`
    `static Screen` | `getLastScreenOf(Display display, int idx, int fromIndex)`
    `MonitorDevice` | `getMainMonitor(RectangleImmutable r)` Returns the `MonitorDevice` with the highest `viewport` `coverage` of the given rectangle in window units.
    `abstract List<MonitorDevice>` | `getMonitorDevices()` Return a list of available `MonitorDevice`s.
    `abstract List<MonitorMode>` | `getMonitorModes()` Return a list of all `MonitorMode`s for all `MonitorDevice`s.
    `abstract int` | `getReferenceCount()`
    `abstract RectangleImmutable` | `getViewport()` See Coordinate System.
    `abstract RectangleImmutable` | `getViewportInWindowUnits()` See Coordinate System.
    `abstract int` | `getWidth()`
    `abstract int` | `getX()` See Coordinate System.
    `abstract int` | `getY()` See Coordinate System.
    `abstract int` | `hashCode()` return precomputed hashCode from FQN `getFQName()`
    `abstract boolean` | `isNativeValid()`
    `abstract void` | `removeMonitorModeListener(MonitorModeListener sml)`
    `abstract int` | `removeReference()` See `Display.removeReference()`
    `void` | `unionOfMonitorViewports(Rectangle viewport, Rectangle viewportInWindowUnits)` Calculates the union of all monitor's `viewport` in pixel- and window units.

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SCREEN_MODE_CHANGE_TIMEOUT

          public static final int SCREEN_MODE_CHANGE_TIMEOUT

      A 10s timeout for screen mode change. It is observed, that some platforms need a notable amount of time for this task, especially in case of rotation change.
      See Also:
        Constant Field Values

    - #### DEBUG

          public static final boolean DEBUG

  - ### Constructor Detail

    - #### Screen

          public Screen()

  - ### Method Detail

    - #### hashCode

          public abstract int hashCode()

      return precomputed hashCode from FQN `getFQName()`
      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals(Object obj)

      return true if obj is of type Display and both FQN `getFQName()` equals
      Overrides:
        `equals` in class `Object`

    - #### createNative

          public abstract void createNative()
                                     throws NativeWindowException

      Manual trigger the native creation, if not done yet..
      This is useful to be able to request the `AbstractGraphicsScreen`, via `getGraphicsScreen()`.
      Otherwise the abstract device won't be available before the dependent component (Window) is realized.

      This method is usually invoke by `addReference()`

      This method invokes `Display.addReference()` after creating the native peer,
      which will issue `Display.createNative()` if the reference count was 0.

      Throws:
        `NativeWindowException` - if the native creation failed.

    - #### destroy

          public abstract void destroy()

      Manually trigger the destruction, incl. native destruction.

      This method is usually invoke by `removeReference()`

      This method invokes `Display.removeReference()` after it's own destruction,
      which will issue `Display.destroy()` if the reference count becomes 0.

    - #### isNativeValid

          public abstract boolean isNativeValid()

    - #### getReferenceCount

          public abstract int getReferenceCount()

      Returns:
        number of references

    - #### addReference

          public abstract int addReference()
                                    throws NativeWindowException

      See `Display.addReference()`
      Returns:
        number of references post operation
      Throws:
        `NativeWindowException` - if the native creation failed.
      See Also:
        `removeReference()`, `#setDestroyWhenUnused(boolean)`, `#getDestroyWhenUnused()`

    - #### removeReference

          public abstract int removeReference()

      See `Display.removeReference()`
      Returns:
        number of references post operation
      See Also:
        `addReference()`, `#setDestroyWhenUnused(boolean)`, `#getDestroyWhenUnused()`

    - #### getGraphicsScreen

          public abstract AbstractGraphicsScreen getGraphicsScreen()

    - #### getIndex

          public abstract int getIndex()

      Returns:
        this Screen index of all Screens of `getDisplay()`.

    - #### getX

          public abstract int getX()

      See Coordinate System.
      Returns:
        the x position of the virtual viewport's top-left origin in pixel units.

    - #### getY

          public abstract int getY()

      See Coordinate System.
      Returns:
        the y position of the virtual viewport's top-left origin in pixel units.

    - #### getWidth

          public abstract int getWidth()

      Returns:
        the rotated virtual viewport's width in pixel units.

    - #### getHeight

          public abstract int getHeight()

      Returns:
        the rotated virtual viewport's height in pixel units.

    - #### getViewport

          public abstract RectangleImmutable getViewport()

      See Coordinate System.
      Returns:
        the rotated virtual viewport, i.e. top-left origin and size, in pixel units.
      See Also:
        `getViewportInWindowUnits()`

    - #### getViewportInWindowUnits

          public abstract RectangleImmutable getViewportInWindowUnits()

      See Coordinate System.
      Returns:
        the rotated virtual viewport, i.e. top-left origin and size, in window units.
      See Also:
        `getViewport()`

    - #### getDisplay

          public abstract Display getDisplay()

      Returns:
        the associated Display

    - #### getFQName

          public abstract String getFQName()

      Returns:
        The screen fully qualified Screen name, which is a key of `Display.getFQName()` + `getIndex()`.

    - #### getMonitorModes

          public abstract List<MonitorMode> getMonitorModes()

      Return a list of all `MonitorMode`s for all `MonitorDevice`s.

      The list is ordered in descending order, see `MonitorMode.compareTo(MonitorMode)`.

    - #### getMonitorDevices

          public abstract List<MonitorDevice> getMonitorDevices()

      Return a list of available `MonitorDevice`s.

    - #### getMainMonitor

          public final MonitorDevice getMainMonitor(RectangleImmutable r)

      Returns the `MonitorDevice` with the highest `viewport` `coverage` of the given rectangle in window units.

      If no coverage is detected the first `MonitorDevice` is returned.

      Parameters:
        `r` - arbitrary rectangle in window units

    - #### unionOfMonitorViewports

          public final void unionOfMonitorViewports(Rectangle viewport,
                                     Rectangle viewportInWindowUnits)

      Calculates the union of all monitor's `viewport` in pixel- and window units.

      Should be equal to `getX()`, `getY()`, `getWidth()` and `getHeight()`, however, some native toolkits may choose a different virtual screen area.

      Parameters:
        `viewport` - storage for result in pixel units, maybe null
        `viewportInWindowUnits` - storage for result in window units, maybe null

    - #### addMonitorModeListener

          public abstract void addMonitorModeListener(MonitorModeListener sml)

      Parameters:
        `sml` - `MonitorModeListener` to be added for `MonitorEvent`

    - #### removeMonitorModeListener

          public abstract void removeMonitorModeListener(MonitorModeListener sml)

      Parameters:
        `sml` - `MonitorModeListener` to be removed from `MonitorEvent`

    - #### getFirstScreenOf

          public static Screen getFirstScreenOf(Display display,
                                int idx,
                                int fromIndex)

      Parameters:
        `type` -
        `name` -
        `fromIndex` - start index, then increasing until found or end of list *
      Returns:

    - #### getLastScreenOf

          public static Screen getLastScreenOf(Display display,
                               int idx,
                               int fromIndex)

      Parameters:
        `type` -
        `name` -
        `fromIndex` - start index, then decreasing until found or end of list. -1 is interpreted as size - 1.
      Returns:

    - #### getAllScreens

          public static Collection<Screen> getAllScreens()

      Returns the global screen collection

    - #### getActiveScreenNumber

          public static int getActiveScreenNumber()

Copyright 2010 JogAmp Community.