public final class Desktop

  1. Object
  2. Desktop

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.

Methods

public static Desktop getInstance()Returns the singleton instance.
public static boolean isSupported()Indicates whether this platform has a windowing system, and therefore whether Window can be used at all.
public Monitor[] getMonitors()Returns every monitor attached to the desktop.
public Monitor getPrimaryMonitor()Returns the monitor the platform treats as the origin of the desktop.
public Monitor getMonitorAt(int x, int y)Returns the monitor containing the given desktop coordinate.
public Monitor getMonitorFor(TopLevelContainer topLevel)Returns the monitor a top level is currently displayed on.
public Rectangle getDesktopBounds()Returns the union of every monitor’s bounds.
public Window[] getWindows()Returns every window currently open, not counting the application’s main form.
public Window getFocusedWindow()Returns the window that currently holds keyboard focus.
public void addMonitorListener(ActionListener l)Adds a listener notified when a monitor is attached, removed or reconfigured.
public void removeMonitorListener(ActionListener l)Removes a previously added monitor listener.
public void addWindowListener(ActionListener l)Adds a listener notified when any window is shown, hidden, moved or resized.
public void removeWindowListener(ActionListener l)Removes a previously added window listener.
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.
public boolean isWindowInputBlocked(int windowId)Whether input aimed at the given window is currently blocked by a modal.
public void windowShowNotify(int windowId)Notifies Codename One that a native window became visible.
public void windowHideNotify(int windowId)Notifies Codename One that a native window stopped being visible.
public void windowFocusChanged(int windowId, boolean gained)Notifies Codename One that a native window gained or lost keyboard focus.
public void windowCloseRequested(int windowId)Notifies Codename One that the user activated a native window’s close control.
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.
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.
public void windowMoved(int windowId)Notifies Codename One that the user moved a native window.
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.
public void windowSizeChanged(int windowId, int w, int h)Notifies Codename One that a native window changed size.
public void monitorsChanged()Notifies Codename One that the set of attached monitors changed.
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.
public int windowWidth(int windowId)The width of one of the additional native windows, or 0 when there is no such window.
public int windowHeight(int windowId)The height of one of the additional native windows, or 0 when there is no such window.
public void windowKeyPressed(int windowId, int keyCode)Pushes a key press event aimed at one native window into Codename One.
public void windowKeyReleased(int windowId, int keyCode)Pushes a key release aimed at one native window into Codename One.
public void windowPointerHoverPressed(int windowId, int[] x, int[] y)Pushes a hover press aimed at one native window into Codename One.
public void windowPointerHoverReleased(int windowId, int[] x, int[] y)Pushes a hover release aimed at one native window into Codename One.
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.
public void windowMagnifyGesture(int windowId, int x, int y, float scale)Dispatches a magnify (pinch) gesture that arrived over a native window.
public void windowRotationGesture(int windowId, int x, int y, float radians)Dispatches a rotation (twist) gesture that arrived over a native window.
public PointerDragActivation windowDragActivation(int windowId)The drag-activation filter belonging to one window, which the implementation applies to that window’s pointer moves.
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.
public void windowPointerDragged(int windowId, int[] x, int[] y)Pushes a pointer drag aimed at one native window into Codename One.
public void windowPointerHover(int windowId, int[] x, int[] y)Pushes a pointer hover event that arrived over a specific native window.
public void windowPointerPressed(int windowId, int[] x, int[] y)Pushes a pointer press aimed at one native window into Codename One.
public void windowPointerReleased(int windowId, int[] x, int[] y)Pushes a pointer release aimed at one native window into Codename One.

Inherited methods

From Object

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

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 int
the x coordinate in desktop space
y int
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 TopLevelContainer
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 ActionListener
the listener to add

removeMonitorListener

public void removeMonitorListener(ActionListener l)
Removes a previously added monitor listener.

Parameters

l ActionListener
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 ActionListener
the listener to add

removeWindowListener

public void removeWindowListener(ActionListener l)
Removes a previously added window listener.

Parameters

l ActionListener
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 int
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 int
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 int
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 int
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 int
the id the port was given when the window was created
gained boolean
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 int
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 int
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 int
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 int
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 int
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 int
the id the port was given when the window was created
w int
the new drawable width
h int
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 int
the window to ask
x int
x in the window’s coordinates
y int
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 int
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 int
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 int
the id the port was given when the window was created
keyCode int
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 int
the id the port was given when the window was created
keyCode int
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 int
the id the port was given when the window was created
x int[]
the x position of the pointer, in window coordinates
y int[]
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 int
the id the port was given when the window was created
x int[]
the x position of the pointer, in window coordinates
y int[]
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 int
the id the port was given when the window was created, or 0 for the application’s main surface
x int
the pointer x position in window pixels
y int
the pointer y position in window pixels
scrollX int
the horizontal scroll amount in display pixels
scrollY int
the vertical scroll amount in display pixels
precise boolean
true if the deltas come from a high resolution device such as a trackpad
modifiers int
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 int
the id the port was given when the window was created
x int
the gesture x position in pixels, relative to that window
y int
the gesture y position in pixels, relative to that window
scale float
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 int
the id the port was given when the window was created
x int
the gesture x position in pixels, relative to that window
y int
the gesture y position in pixels, relative to that window
radians float
the incremental rotation in radians, positive is clockwise

windowDragActivation

public PointerDragActivation windowDragActivation(int windowId)
The drag-activation filter belonging to one window, which the implementation applies to that window’s pointer moves.

Parameters

windowId int
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 Component
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 int
the id the port was given when the window was created
x int[]
the x positions of the pointer
y int[]
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 int
the id the port was given when the window was created
x int[]
the x position of the pointer, in window coordinates
y int[]
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 int
the id the port was given when the window was created
x int[]
the x positions of the pointer
y int[]
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 int
the id the port was given when the window was created
x int[]
the x positions of the pointer
y int[]
the y positions of the pointer