# Class Desktop

java.lang.Object
com.codename1.ui.Desktop

public final class Desktop extends Object

The desktop a windowed application runs on: the monitors attached to it and the `Window` instances open on them.

This sits alongside `Display` rather than replacing any of it. `Display` answers "how big is the application's main surface", which is the only question a phone has; `Desktop` answers "what screens exist and what windows are open", which only a windowing system can answer.

Every method degrades safely on a platform with no windowing system: `#getWindows()` returns an empty array, `#getMonitors()` returns a single monitor describing the main display, and `#getFocusedWindow()` returns null. Only constructing a `Window` throws.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addMonitorListener(ActionListener l)`
  Adds a listener notified when a monitor is attached, removed or reconfigured.
  `void`
  `addWindowListener(ActionListener l)`
  Adds a listener notified when any window is shown, hidden, moved or resized.
  `Rectangle`
  `getDesktopBounds()`
  Returns the union of every monitor's bounds.
  `Window`
  `getFocusedWindow()`
  Returns the window that currently holds keyboard focus.
  `static Desktop`
  `getInstance()`
  Returns the singleton instance.
  `Monitor`
  `getMonitorAt(int x, int y)`
  Returns the monitor containing the given desktop coordinate.
  `Monitor`
  `getMonitorFor(TopLevelContainer topLevel)`
  Returns the monitor a top level is currently displayed on.
  `Monitor[]`
  `getMonitors()`
  Returns every monitor attached to the desktop.
  `Monitor`
  `getPrimaryMonitor()`
  Returns the monitor the platform treats as the origin of the desktop.
  `Object`
  `getWindowPeerForComponent(Component cmp)`
  Returns the native window peer owning the given component, or null when it belongs to the application's main surface.
  `Window[]`
  `getWindows()`
  Returns every window currently open, not counting the application's main form.
  `static boolean`
  `isSupported()`
  Indicates whether this platform has a windowing system, and therefore whether `Window` can be used at all.
  `boolean`
  `isWindowInputBlocked(int windowId)`
  Whether input aimed at the given window is currently blocked by a modal.
  `void`
  `monitorsChanged()`
  Notifies Codename One that the set of attached monitors changed.
  `void`
  `removeMonitorListener(ActionListener l)`
  Removes a previously added monitor listener.
  `void`
  `removeWindowListener(ActionListener l)`
  Removes a previously added window listener.
  `void`
  `windowActivationFailed(int windowId)`
  Notifies Codename One that the platform refused to create a window's native surface, so the window will never appear.
  `Window`
  `windowById(int windowId)`
  Returns the window carrying the given framework assigned id, which is how an event that arrived off the event dispatch thread is routed back to its tree.
  `void`
  `windowClosedNatively(int windowId)`
  Notifies Codename One that the platform has already destroyed a window's native surface, so the window is gone whatever the application would prefer.
  `void`
  `windowCloseRequested(int windowId)`
  Notifies Codename One that the user activated a native window's close control.
  `com.codename1.impl.PointerDragActivation`
  `windowDragActivation(int windowId)`
  The drag-activation filter belonging to one window, which the implementation applies to that window's pointer moves.
  `int`
  `windowDragRegionStatus(int windowId, int x, int y)`
  Indicates whether input aimed at the given window is currently blocked by a modal window above it.
  `void`
  `windowFocusChanged(int windowId, boolean gained)`
  Notifies Codename One that a native window gained or lost keyboard focus.
  `int`
  `windowHeight(int windowId)`
  The height of one of the additional native windows, or 0 when there is no such window.
  `void`
  `windowHideNotify(int windowId)`
  Notifies Codename One that a native window stopped being visible.
  `void`
  `windowKeyPressed(int windowId, int keyCode)`
  Pushes a key press event aimed at one native window into Codename One.
  `void`
  `windowKeyReleased(int windowId, int keyCode)`
  Pushes a key release aimed at one native window into Codename One.
  `void`
  `windowMagnifyGesture(int windowId, int x, int y, float scale)`
  Dispatches a magnify (pinch) gesture that arrived over a native window.
  `void`
  `windowMonitorChanged(int windowId)`
  Notifies Codename One that a native window moved to a monitor with different characteristics, so that its scale and layout are recomputed.
  `boolean`
  `windowMouseWheelEvent(int windowId, int x, int y, int scrollX, int scrollY, boolean precise, int modifiers)`
  Dispatches a wheel event that arrived over a native window.
  `void`
  `windowMoved(int windowId)`
  Notifies Codename One that the user moved a native window.
  `void`
  `windowPointerDragged(int windowId, int[] x, int[] y)`
  Pushes a pointer drag aimed at one native window into Codename One.
  `void`
  `windowPointerHover(int windowId, int[] x, int[] y)`
  Pushes a pointer hover event that arrived over a specific native window.
  `void`
  `windowPointerHoverPressed(int windowId, int[] x, int[] y)`
  Pushes a hover press aimed at one native window into Codename One.
  `void`
  `windowPointerHoverReleased(int windowId, int[] x, int[] y)`
  Pushes a hover release aimed at one native window into Codename One.
  `void`
  `windowPointerPressed(int windowId, int[] x, int[] y)`
  Pushes a pointer press aimed at one native window into Codename One.
  `void`
  `windowPointerReleased(int windowId, int[] x, int[] y)`
  Pushes a pointer release aimed at one native window into Codename One.
  `void`
  `windowRotationGesture(int windowId, int x, int y, float radians)`
  Dispatches a rotation (twist) gesture that arrived over a native window.
  `void`
  `windowShowNotify(int windowId)`
  Notifies Codename One that a native window became visible.
  `void`
  `windowSizeChanged(int windowId, int w, int h)`
  Notifies Codename One that a native window changed size.
  `int`
  `windowWidth(int windowId)`
  The width of one of the additional native windows, or 0 when there is no such window.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### getInstance

    public static Desktop getInstance()

    Returns the singleton instance.

    ###### Returns

    the desktop instance

  - ### isSupported

    public static boolean isSupported()

    Indicates whether this platform has a windowing system, and therefore whether `Window` can be used at all.

    ###### Returns

    true if additional native windows can be opened

  - ### getMonitors

    public Monitor[] getMonitors()

    Returns every monitor attached to the desktop.

    On a platform with no windowing system this reports a single monitor covering the main display, so layout code that positions against a monitor works everywhere.

    ###### Returns

    the monitors, never empty and never null

  - ### getPrimaryMonitor

    public Monitor getPrimaryMonitor()

    Returns the monitor the platform treats as the origin of the desktop.

    ###### Returns

    the primary monitor

  - ### getMonitorAt

    public Monitor getMonitorAt(int x, int y)

    Returns the monitor containing the given desktop coordinate.

    ###### Parameters

    - `x`: the x coordinate in desktop space

    - `y`: the y coordinate in desktop space

    ###### Returns

    the monitor containing that point, or the primary monitor when none does

  - ### getMonitorFor

    public Monitor getMonitorFor(TopLevelContainer topLevel)

    Returns the monitor a top level is currently displayed on.

    ###### Parameters

    - `topLevel`: the form or window to locate

    ###### Returns

    the monitor it sits on, or the primary monitor when that cannot be determined

  - ### getDesktopBounds

    public Rectangle getDesktopBounds()

    Returns the union of every monitor's bounds.

    ###### Returns

    the whole desktop area

  - ### getWindows

    public Window[] getWindows()

    Returns every window currently open, not counting the application's main form.

    ###### Returns

    the open windows, empty when there are none or the platform has no windows

  - ### getFocusedWindow

    public Window getFocusedWindow()

    Returns the window that currently holds keyboard focus.

    ###### Returns

    the focused window, or null when the main form has focus or none is open

  - ### addMonitorListener

    public void addMonitorListener(ActionListener l)

    Adds a listener notified when a monitor is attached, removed or reconfigured.

    ###### Parameters

    - `l`: the listener to add

  - ### removeMonitorListener

    public void removeMonitorListener(ActionListener l)

    Removes a previously added monitor listener.

    ###### Parameters

    - `l`: the listener to remove

  - ### addWindowListener

    public void addWindowListener(ActionListener l)

    Adds a listener notified when any window is shown, hidden, moved or resized.

    This is the multi-window counterpart of `Display#addWindowListener(com.codename1.ui.events.ActionListener)`, which continues to report only the application's main window.

    ###### Parameters

    - `l`: the listener to add

  - ### removeWindowListener

    public void removeWindowListener(ActionListener l)

    Removes a previously added window listener.

    ###### Parameters

    - `l`: the listener to remove

  - ### windowById

    public Window windowById(int windowId)

    Returns the window carrying the given framework assigned id, which is how an event that arrived off the event dispatch thread is routed back to its tree.

    ###### Parameters

    - `windowId`: the id from `Window#getWindowId()`

    ###### Returns

    the matching window, or null when none is open with that id

  - ### isWindowInputBlocked

    public boolean isWindowInputBlocked(int windowId)

    Whether input aimed at the given window is currently blocked by a modal.

    Public because the implementation needs it: a wheel gesture is played as four steps queued on the event dispatch thread, and a listener can show a modal between the first check and the last step.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    ###### Returns

    true when input to that window is currently blocked

  - ### windowShowNotify

    public void windowShowNotify(int windowId)

    Notifies Codename One that a native window became visible.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

  - ### windowHideNotify

    public void windowHideNotify(int windowId)

    Notifies Codename One that a native window stopped being visible.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

  - ### windowFocusChanged

    public void windowFocusChanged(int windowId, boolean gained)

    Notifies Codename One that a native window gained or lost keyboard focus. Marshalled onto the event dispatch thread, since it runs application code.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `gained`: true when the window gained focus

  - ### windowCloseRequested

    public void windowCloseRequested(int windowId)

    Notifies Codename One that the user activated a native window's close control. Marshalled onto the event dispatch thread, since it runs application code and may dispose the window.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

  - ### windowClosedNatively

    public void windowClosedNatively(int windowId)

    Notifies Codename One that the platform has already destroyed a window's native surface, so the window is gone whatever the application would prefer.

    Distinct from `#windowCloseRequested(int)`, which asks. Some platforms do not offer the close control as a question: a Mac Catalyst scene is disconnected after the fact, with nothing left to veto. Reporting that as a request would let `DO_NOTHING_ON_CLOSE` leave a registered window painting into a surface that no longer exists, so it is reported as what it is and the window is disposed.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

  - ### windowActivationFailed

    public void windowActivationFailed(int windowId)

    Notifies Codename One that the platform refused to create a window's native surface, so the window will never appear.

    Separate from `#windowHideNotify(int)` because that one means "minimized", which keeps a modal window's registration: a modal that never appeared would otherwise block input to every other window while `showModal()` waited for it.

    ###### Parameters

    - `windowId`: the window whose native surface could not be created

  - ### windowMoved

    public void windowMoved(int windowId)

    Notifies Codename One that the user moved a native window.

    Separate from `#windowMonitorChanged(int)`, which is only for a move that carried the window onto a different display: an ordinary move within one monitor still has to reach the listeners, or nothing can persist a window's position.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

  - ### windowMonitorChanged

    public void windowMonitorChanged(int windowId)

    Notifies Codename One that a native window moved to a monitor with different characteristics, so that its scale and layout are recomputed.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

  - ### windowSizeChanged

    public void windowSizeChanged(int windowId, int w, int h)

    Notifies Codename One that a native window changed size. Invoked by the implementation.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `w`: the new drawable width

    - `h`: the new drawable height

  - ### monitorsChanged

    public void monitorsChanged()
    Notifies Codename One that the set of attached monitors changed.

  - ### windowDragRegionStatus

    public int windowDragRegionStatus(int windowId, int x, int y)

    Indicates whether input aimed at the given window is currently blocked by a modal window above it. The drag-region status at a point inside one of the additional native windows, used by the implementation's drag activation filter.

    ###### Parameters

    - `windowId`: the window to ask

    - `x`: x in the window's coordinates

    - `y`: y in the window's coordinates

    ###### Returns

    the drag region status, or `Component#DRAG_REGION_NOT_DRAGGABLE` when there is no such window

  - ### windowWidth

    public int windowWidth(int windowId)

    The width of one of the additional native windows, or 0 when there is no such window.

    ###### Parameters

    - `windowId`: the window to ask

    ###### Returns

    the window's width in Codename One coordinates

  - ### windowHeight

    public int windowHeight(int windowId)

    The height of one of the additional native windows, or 0 when there is no such window.

    ###### Parameters

    - `windowId`: the window to ask

    ###### Returns

    the window's height in Codename One coordinates

  - ### windowKeyPressed

    public void windowKeyPressed(int windowId, int keyCode)

    Pushes a key press event aimed at one native window into Codename One. Invoked by the implementation, off the event dispatch thread.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `keyCode`: keycode of the key event

  - ### windowKeyReleased

    public void windowKeyReleased(int windowId, int keyCode)

    Pushes a key release aimed at one native window into Codename One. Invoked by the implementation, off the event dispatch thread.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `keyCode`: keycode of the key event

  - ### windowPointerHoverPressed

    public void windowPointerHoverPressed(int windowId, int[] x, int[] y)

    Pushes a hover press aimed at one native window into Codename One. Invoked by the implementation, off the event dispatch thread.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `x`: the x position of the pointer, in window coordinates

    - `y`: the y position of the pointer, in window coordinates

  - ### windowPointerHoverReleased

    public void windowPointerHoverReleased(int windowId, int[] x, int[] y)

    Pushes a hover release aimed at one native window into Codename One. Invoked by the implementation, off the event dispatch thread.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `x`: the x position of the pointer, in window coordinates

    - `y`: the y position of the pointer, in window coordinates

  - ### windowMouseWheelEvent

    public boolean windowMouseWheelEvent(int windowId, int x, int y, int scrollX, int scrollY, boolean precise, int modifiers)

    Dispatches a wheel event that arrived over a native window.

    A port with desktop windows has to route the wheel explicitly: the main surface version resolves the component from the current form, so a wheel over a second window would either do nothing or scroll the main form instead.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created, or 0 for the application's main surface

    - `x`: the pointer x position in window pixels

    - `y`: the pointer y position in window pixels

    - `scrollX`: the horizontal scroll amount in display pixels

    - `scrollY`: the vertical scroll amount in display pixels

    - `precise`: true if the deltas come from a high resolution device such as a trackpad

    - `modifiers`: bitmask of the held keyboard modifiers

    ###### Returns

    true if the wheel was acted on -- a listener consumed it, a component handled it, or something scrolled. False means nothing under the cursor could move, which is the answer a port needs to pass the gesture to whatever hosts the app; it is NOT an invitation to emulate the wheel with pointer events.

  - ### windowMagnifyGesture

    public void windowMagnifyGesture(int windowId, int x, int y, float scale)

    Dispatches a magnify (pinch) gesture that arrived over a native window. Window 0 is the application's main surface.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `x`: the gesture x position in pixels, relative to that window

    - `y`: the gesture y position in pixels, relative to that window

    - `scale`: the magnification scale, larger than 1 zooms in and smaller than 1 zooms out

  - ### windowRotationGesture

    public void windowRotationGesture(int windowId, int x, int y, float radians)

    Dispatches a rotation (twist) gesture that arrived over a native window. Window 0 is the application's main surface.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `x`: the gesture x position in pixels, relative to that window

    - `y`: the gesture y position in pixels, relative to that window

    - `radians`: the incremental rotation in radians, positive is clockwise

  - ### windowDragActivation

    public com.codename1.impl.PointerDragActivation windowDragActivation(int windowId)

    The drag-activation filter belonging to one window, which the implementation applies to that window's pointer moves.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    ###### Returns

    the window's filter, or null when no window holds that id

  - ### getWindowPeerForComponent

    public Object getWindowPeerForComponent(Component cmp)

    Returns the native window peer owning the given component, or null when it belongs to the application's main surface. Ports use this to place native peers and native text editors into the correct window.

    It lives here rather than on `Display` because this class owns the windows; `Display` answers for the application's single main surface and knowing which window a component is in is not a question about that surface.

    ###### Parameters

    - `cmp`: the component to locate

    ###### Returns

    the owning window's native peer, or null for the main surface

  - ### windowPointerDragged

    public void windowPointerDragged(int windowId, int[] x, int[] y)

    Pushes a pointer drag aimed at one native window into Codename One. Invoked by the implementation, off the event dispatch thread.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `x`: the x positions of the pointer

    - `y`: the y positions of the pointer

  - ### windowPointerHover

    public void windowPointerHover(int windowId, int[] x, int[] y)

    Pushes a pointer hover event that arrived over a specific native window.

    A port with desktop windows has to say which window the pointer was over, or hovering a second window sends the event to whatever the main form has at the same coordinates -- so the window gets no tooltips and the main form gets spurious ones.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `x`: the x position of the pointer, in window coordinates

    - `y`: the y position of the pointer, in window coordinates

  - ### windowPointerPressed

    public void windowPointerPressed(int windowId, int[] x, int[] y)

    Pushes a pointer press aimed at one native window into Codename One. Invoked by the implementation, off the event dispatch thread.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `x`: the x positions of the pointer

    - `y`: the y positions of the pointer

  - ### windowPointerReleased

    public void windowPointerReleased(int windowId, int[] x, int[] y)

    Pushes a pointer release aimed at one native window into Codename One. Invoked by the implementation, off the event dispatch thread.

    ###### Parameters

    - `windowId`: the id the port was given when the window was created

    - `x`: the x positions of the pointer

    - `y`: the y positions of the pointer