public interface TopLevelContainer

Known subtypesProgress, Dialog, Form, Window

The contract shared by the two things that can sit at the root of a Codename One component hierarchy: Form, which fills the application’s main surface, and Window, which is a separate native operating system window on the desktop.

Code that needs to work against “whatever top level I happen to be in” should resolve it with Component#getTopLevelContainer() and talk to it through this interface, rather than through Component#getComponentForm(). The latter keeps its original meaning and returns null for a component hosted inside a Window.

This interface is implemented by Form and Window only. It is not intended to be implemented outside the framework – several of its collaborators are package private – and it may gain members in any release.

Members that belong to a Component or a Container are deliberately absent – reach them through #asContainer() instead. So are the parts of Form that model mobile navigation, such as form transitions, the back command and the menu bar; those have no meaning for a desktop window.

Methods

`public abstract <C extends Component> void addComponentAwaitingRelease(C c)`	Returns this top level as a `Container`.
`public abstract <C extends Component> void removeComponentAwaitingRelease(C c)`	Stops tracking a component that was waiting for a pointer release.
`public abstract void clearComponentsAwaitingRelease()`	Drops every component waiting for a pointer release, used when a gesture is taken over by something else – a pull to refresh, for instance.
`public abstract` `Container asContainer()`
`public abstract` `Container getContentPane()`	Returns the container holding the application content of this top level.
`public abstract` `Container getLayeredPane()`	Returns the layered pane covering the content area, creating it if needed.
`public abstract` `Container getLayeredPane(Class c, boolean top)`	Returns the layer belonging to the given class within the content-area layered pane, creating it if needed.
`public abstract` `Container getLayeredPane(Class c, int zIndex)`	Returns the layer belonging to the given class within the content-area layered pane at an explicit depth, creating it if needed.
`public abstract` `Container getFormLayeredPane(Class c, boolean top)`	Returns the layer belonging to the given class within the layered pane that spans the whole top level, including the title area, creating it if needed.
`public abstract` `Painter getGlassPane()`	Returns the painter drawn above everything else in this top level.
`public abstract void setGlassPane(Painter glassPane)`	Sets the painter drawn above everything else in this top level.
`public abstract` `String getTitle()`	Returns the title text.
`public abstract void setTitle(String title)`	Sets the title text.
`public abstract void addCommand(Command cmd)`	Adds a command to this top level.
`public abstract void removeCommand(Command cmd)`	Removes a command from this top level.
`public abstract void removeAllCommands()`	Removes every command from this top level.
`public abstract int getCommandCount()`	Returns the number of commands.
`public abstract` `Command getCommand(int index)`	Returns the command at the given offset.
`public abstract void addCommandListener(ActionListener l)`	Adds a listener notified when a command is activated.
`public abstract void removeCommandListener(ActionListener l)`	Removes a previously added command listener.
`public abstract` `AnimationManager getAnimationManager()`	Returns the animation manager coordinating mutations of this top level.
`public abstract void registerAnimated(Animation cmp)`	Registers an animation that is invoked on every frame of this top level.
`public abstract void deregisterAnimated(Animation cmp)`	Removes a previously registered animation.
`public abstract boolean grabAnimationLock()`	Takes the animation lock, blocking until no animation is in progress.
`public abstract void releaseAnimationLock()`	Releases a previously taken animation lock.
`public abstract` `Component getFocused()`	Returns the component currently owning focus.
`public abstract void setFocused(Component focused)`	Moves focus to the given component.
`public abstract boolean isCyclicFocus()`	Returns true when focus traversal wraps around at the edges.
`public abstract void setCyclicFocus(boolean cyclicFocus)`	Sets whether focus traversal wraps around at the edges.
`public abstract boolean isSingleFocusMode()`	Returns true when only one component in this top level can take focus.
`public abstract` `Form.TabIterator getTabIterator(Component start)`	Returns an iterator walking the components in traversal order.
`public abstract void scrollComponentToVisible(Component c)`	Scrolls so that the given component becomes visible.
`public abstract void addKeyListener(int keyCode,` `ActionListener listener)`	Adds a key binding scoped to this top level.
`public abstract void removeKeyListener(int keyCode,` `ActionListener listener)`	Removes a previously added key binding.
`public abstract boolean isEditing()`	Returns true when a component in this top level is being edited.
`public abstract void stopEditing(Runnable onFinish)`	Stops the in-progress edit and invokes the callback once it has finished.
`public abstract` `Component findCurrentlyEditingComponent()`	Returns the component currently being edited.
`public abstract` `VirtualInputDevice getCurrentInputDevice()`	Returns the virtual input device currently open for this top level.
`public abstract void setCurrentInputDevice(VirtualInputDevice device) throws Exception`	Opens a virtual input device, closing whichever one was open before it.
`public abstract` `UIManager getUIManager()`	Returns the theme manager used to style this top level.
`public abstract void setUIManager(UIManager uiManager)`	Sets the theme manager used to style this top level.
`public abstract int getTintColor()`	Returns the region of this top level that is guaranteed not to be obscured by system chrome such as a notch or a rounded corner.
`public abstract void setTintColor(int tintColor)`	Sets the colour painted over this top level while a dialog or menu covers it.
`public abstract boolean isTopLevelShowing()`	Whether this top level is the one the user can currently see.
`public abstract` `Rectangle getSafeArea()`	Returns the region of this top level that is guaranteed not to be obscured by system chrome such as a notch or a rounded corner.
`public abstract int getInvisibleAreaUnderVKB()`	Returns the height hidden behind the virtual keyboard, which is zero on a platform without one.
`public abstract int getDragRegionStatus(int x, int y)`	Indicates whether the given coordinate begins a drag of the whole top level rather than of a component inside it.
`public abstract boolean isEnableCursors()`	Returns true when components may change the mouse cursor.
`public abstract void setEnableCursors(boolean e)`	Sets whether components may change the mouse cursor.
`public abstract` `TextSelection getTextSelection()`	Returns the text selection support for this top level.
`public abstract void show()`	Makes this top level visible.
`public abstract void addShowListener(ActionListener l)`	Adds a listener notified whenever this top level is shown.
`public abstract void removeShowListener(ActionListener l)`	Removes a previously added show listener.
`public abstract void addSizeChangedListener(ActionListener l)`	Adds a listener notified whenever this top level changes size.
`public abstract void removeSizeChangedListener(ActionListener l)`	Removes a previously added size changed listener.
`public abstract void dispatchCommand(Command cmd, ActionEvent ev)`	Dispatches a command to this top level’s command handling, which is how a component that holds a `Command` triggers it without knowing whether it lives in a `Form` or a `Window`.

Method details

addComponentAwaitingRelease

public abstract <C extends Component> void addComponentAwaitingRelease(C c)

Returns this top level as a Container.

A Java interface cannot extend a class, so without this a TopLevelContainer reference could not be handed to anything expecting a Component.

Parameters

c C: the component awaiting a release

Returns

this instance, as a Container Records a component that is waiting for a pointer release, so the top level can release it if the gesture ends somewhere else.

removeComponentAwaitingRelease

public abstract <C extends Component> void removeComponentAwaitingRelease(C c)

Stops tracking a component that was waiting for a pointer release.

Parameters

c C: the component to stop tracking

clearComponentsAwaitingRelease

public abstract void clearComponentsAwaitingRelease()

Drops every component waiting for a pointer release, used when a gesture is taken over by something else – a pull to refresh, for instance.

asContainer

public abstract Container asContainer()

getContentPane

public abstract Container getContentPane()

Returns the container holding the application content of this top level.

Returns

the content pane

getLayeredPane

public abstract Container getLayeredPane()

Returns the layered pane covering the content area, creating it if needed.

Returns

the layered pane

getLayeredPane

public abstract Container getLayeredPane(Class c, boolean top)

Returns the layer belonging to the given class within the content-area layered pane, creating it if needed.

Parameters

c Class: the class owning the layer
top boolean: true to place the layer above the existing layers

Returns

the layer for the given class

getLayeredPane

public abstract Container getLayeredPane(Class c, int zIndex)

Returns the layer belonging to the given class within the content-area layered pane at an explicit depth, creating it if needed.

Parameters

c Class: the class owning the layer
zIndex int: the depth at which the layer should sit

Returns

the layer for the given class

getFormLayeredPane

public abstract Container getFormLayeredPane(Class c, boolean top)

Returns the layer belonging to the given class within the layered pane that spans the whole top level, including the title area, creating it if needed.

Parameters

c Class: the class owning the layer
top boolean: true to place the layer above the existing layers

Returns

the layer for the given class

getGlassPane

public abstract Painter getGlassPane()

Returns the painter drawn above everything else in this top level.

Returns

the glass pane painter, or null when none is installed

setGlassPane

public abstract void setGlassPane(Painter glassPane)

Sets the painter drawn above everything else in this top level.

Parameters

glassPane Painter: the painter to install, or null to remove the current one

getTitle

public abstract String getTitle()

Returns the title text.

Returns

the title

setTitle

public abstract void setTitle(String title)

Sets the title text.

Parameters

title String: the title to display

addCommand

public abstract void addCommand(Command cmd)

Adds a command to this top level.

Parameters

cmd Command: the command to add

removeCommand

public abstract void removeCommand(Command cmd)

Removes a command from this top level.

Parameters

cmd Command: the command to remove

removeAllCommands

public abstract void removeAllCommands()

Removes every command from this top level.

getCommandCount

public abstract int getCommandCount()

Returns the number of commands.

Returns

the command count

getCommand

public abstract Command getCommand(int index)

Returns the command at the given offset.

Parameters

index int: the offset of the command

Returns

the command at that offset

addCommandListener

public abstract void addCommandListener(ActionListener l)

Adds a listener notified when a command is activated.

Parameters

l ActionListener: the listener to add

removeCommandListener

public abstract void removeCommandListener(ActionListener l)

Removes a previously added command listener.

Parameters

l ActionListener: the listener to remove

getAnimationManager

public abstract AnimationManager getAnimationManager()

Returns the animation manager coordinating mutations of this top level.

Returns

the animation manager

registerAnimated

public abstract void registerAnimated(Animation cmp)

Registers an animation that is invoked on every frame of this top level.

Parameters

cmp Animation: the animation to register

deregisterAnimated

public abstract void deregisterAnimated(Animation cmp)

Removes a previously registered animation.

Parameters

cmp Animation: the animation to remove

grabAnimationLock

public abstract boolean grabAnimationLock()

Takes the animation lock, blocking until no animation is in progress.

Returns

true if the lock was taken

releaseAnimationLock

public abstract void releaseAnimationLock()

Releases a previously taken animation lock.

getFocused

public abstract Component getFocused()

Returns the component currently owning focus.

Returns

the focus owner, or null when nothing is focused

setFocused

public abstract void setFocused(Component focused)

Moves focus to the given component.

Parameters

focused Component: the component that should take focus

isCyclicFocus

public abstract boolean isCyclicFocus()

Returns true when focus traversal wraps around at the edges.

Returns

true if focus is cyclic

setCyclicFocus

public abstract void setCyclicFocus(boolean cyclicFocus)

Sets whether focus traversal wraps around at the edges.

Parameters

cyclicFocus boolean: true to make focus cyclic

isSingleFocusMode

public abstract boolean isSingleFocusMode()

Returns true when only one component in this top level can take focus.

Returns

true if this is a single focus top level

getTabIterator

public abstract Form.TabIterator getTabIterator(Component start)

Returns an iterator walking the components in traversal order.

Parameters

start Component: the component to start from

Returns

the traversal iterator

scrollComponentToVisible

public abstract void scrollComponentToVisible(Component c)

Scrolls so that the given component becomes visible.

Parameters

c Component: the component to reveal

addKeyListener

public abstract void addKeyListener(int keyCode, ActionListener listener)

Adds a key binding scoped to this top level.

Parameters

keyCode int: the key code to bind
listener ActionListener: the listener invoked for that key

removeKeyListener

public abstract void removeKeyListener(int keyCode, ActionListener listener)

Removes a previously added key binding.

Parameters

keyCode int: the bound key code
listener ActionListener: the listener to remove

isEditing

public abstract boolean isEditing()

Returns true when a component in this top level is being edited.

Returns

true if editing is in progress

stopEditing

public abstract void stopEditing(Runnable onFinish)

Stops the in-progress edit and invokes the callback once it has finished.

Parameters

onFinish Runnable: invoked once editing has stopped

findCurrentlyEditingComponent

public abstract Component findCurrentlyEditingComponent()

Returns the component currently being edited.

Returns

the edited component, or null when nothing is being edited

getCurrentInputDevice

public abstract VirtualInputDevice getCurrentInputDevice()

Returns the virtual input device currently open for this top level.

Returns

the open input device, or null when none is open

setCurrentInputDevice

public abstract void setCurrentInputDevice(VirtualInputDevice device)
throws Exception

Opens a virtual input device, closing whichever one was open before it.

Parameters

device VirtualInputDevice: the device to open, or null to close the current one

Throws

Exception: if the previously open device failed to close

getUIManager

public abstract UIManager getUIManager()

Returns the theme manager used to style this top level.

Returns

the UI manager

setUIManager

public abstract void setUIManager(UIManager uiManager)

Sets the theme manager used to style this top level.

Parameters

uiManager UIManager: the UI manager to use

getTintColor

public abstract int getTintColor()

Returns the region of this top level that is guaranteed not to be obscured by system chrome such as a notch or a rounded corner.

Returns

the safe area rectangle The colour painted over this top level while a dialog or menu covers it, including its alpha in the high byte.

setTintColor

public abstract void setTintColor(int tintColor)

Sets the colour painted over this top level while a dialog or menu covers it.

Parameters

tintColor int: the tint colour, alpha in the high byte

isTopLevelShowing

public abstract boolean isTopLevelShowing()

Whether this top level is the one the user can currently see.

Display#getCurrent() only ever names a Form, so comparing against it answers false for every window – which is why anything that gated on it stopped working the moment it was put in one. A window is on screen in its own right, and answers for itself.

Returns

true when this top level is showing

getSafeArea

public abstract Rectangle getSafeArea()

Returns the region of this top level that is guaranteed not to be obscured by system chrome such as a notch or a rounded corner.

Returns

the safe area rectangle

getInvisibleAreaUnderVKB

public abstract int getInvisibleAreaUnderVKB()

Returns the height hidden behind the virtual keyboard, which is zero on a platform without one.

Returns

the obscured height in pixels

getDragRegionStatus

public abstract int getDragRegionStatus(int x, int y)

Indicates whether the given coordinate begins a drag of the whole top level rather than of a component inside it.

Parameters

x int: the x coordinate
y int: the y coordinate

Returns

the drag region status for that coordinate

isEnableCursors

public abstract boolean isEnableCursors()

Returns true when components may change the mouse cursor.

Returns

true if cursors are enabled

setEnableCursors

public abstract void setEnableCursors(boolean e)

Sets whether components may change the mouse cursor.

Parameters

e boolean: true to enable cursors

getTextSelection

public abstract TextSelection getTextSelection()

Returns the text selection support for this top level.

Returns

the text selection

show

public abstract void show()

Makes this top level visible.

addShowListener

public abstract void addShowListener(ActionListener l)

Adds a listener notified whenever this top level is shown.

Parameters

l ActionListener: the listener to add

removeShowListener

public abstract void removeShowListener(ActionListener l)

Removes a previously added show listener.

Parameters

l ActionListener: the listener to remove

addSizeChangedListener

public abstract void addSizeChangedListener(ActionListener l)

Adds a listener notified whenever this top level changes size.

Parameters

l ActionListener: the listener to add

removeSizeChangedListener

public abstract void removeSizeChangedListener(ActionListener l)

Removes a previously added size changed listener.

Parameters

l ActionListener: the listener to remove

dispatchCommand

public abstract void dispatchCommand(Command cmd, ActionEvent ev)

Dispatches a command to this top level’s command handling, which is how a component that holds a Command triggers it without knowing whether it lives in a Form or a Window.

Parameters

cmd Command: the command to dispatch
ev ActionEvent: the event to dispatch