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 a listener consumed the wheel event

    • 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