# Interface TopLevelContainer

All Known Implementing Classes:
  `Dialog, Form, Progress, Window`

public interface TopLevelContainer

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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addCommand(Command cmd)`
  Adds a command to this top level.
  `void`
  `addCommandListener(ActionListener l)`
  Adds a listener notified when a command is activated.
  `<C extends Component>
  void`
  `addComponentAwaitingRelease(C c)`
  Returns this top level as a `Container`.
  `void`
  `addKeyListener(int keyCode, ActionListener listener)`
  Adds a key binding scoped to this top level.
  `void`
  `addShowListener(ActionListener l)`
  Adds a listener notified whenever this top level is shown.
  `void`
  `addSizeChangedListener(ActionListener l)`
  Adds a listener notified whenever this top level changes size.
  `Container`
  `asContainer()`
  `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.
  `void`
  `deregisterAnimated(Animation cmp)`
  Removes a previously registered animation.
  `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`.
  `Component`
  `findCurrentlyEditingComponent()`
  Returns the component currently being edited.
  `AnimationManager`
  `getAnimationManager()`
  Returns the animation manager coordinating mutations of this top level.
  `Command`
  `getCommand(int index)`
  Returns the command at the given offset.
  `int`
  `getCommandCount()`
  Returns the number of commands.
  `Container`
  `getContentPane()`
  Returns the container holding the application content of this top level.
  `VirtualInputDevice`
  `getCurrentInputDevice()`
  Returns the virtual input device currently open for this top level.
  `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.
  `Component`
  `getFocused()`
  Returns the component currently owning focus.
  `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.
  `Painter`
  `getGlassPane()`
  Returns the painter drawn above everything else in this top level.
  `int`
  `getInvisibleAreaUnderVKB()`
  Returns the height hidden behind the virtual keyboard, which is zero on a platform without one.
  `Container`
  `getLayeredPane()`
  Returns the layered pane covering the content area, creating it if needed.
  `Container`
  `getLayeredPane(Class c, boolean top)`
  Returns the layer belonging to the given class within the content-area layered pane, creating it if needed.
  `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.
  `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.
  `Form.TabIterator`
  `getTabIterator(Component start)`
  Returns an iterator walking the components in traversal order.
  `TextSelection`
  `getTextSelection()`
  Returns the text selection support for this top level.
  `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.
  `String`
  `getTitle()`
  Returns the title text.
  `UIManager`
  `getUIManager()`
  Returns the theme manager used to style this top level.
  `boolean`
  `grabAnimationLock()`
  Takes the animation lock, blocking until no animation is in progress.
  `boolean`
  `isCyclicFocus()`
  Returns true when focus traversal wraps around at the edges.
  `boolean`
  `isEditing()`
  Returns true when a component in this top level is being edited.
  `boolean`
  `isEnableCursors()`
  Returns true when components may change the mouse cursor.
  `boolean`
  `isSingleFocusMode()`
  Returns true when only one component in this top level can take focus.
  `boolean`
  `isTopLevelShowing()`
  Whether this top level is the one the user can currently see.
  `void`
  `registerAnimated(Animation cmp)`
  Registers an animation that is invoked on every frame of this top level.
  `void`
  `releaseAnimationLock()`
  Releases a previously taken animation lock.
  `void`
  `removeAllCommands()`
  Removes every command from this top level.
  `void`
  `removeCommand(Command cmd)`
  Removes a command from this top level.
  `void`
  `removeCommandListener(ActionListener l)`
  Removes a previously added command listener.
  `<C extends Component>
  void`
  `removeComponentAwaitingRelease(C c)`
  Stops tracking a component that was waiting for a pointer release.
  `void`
  `removeKeyListener(int keyCode, ActionListener listener)`
  Removes a previously added key binding.
  `void`
  `removeShowListener(ActionListener l)`
  Removes a previously added show listener.
  `void`
  `removeSizeChangedListener(ActionListener l)`
  Removes a previously added size changed listener.
  `void`
  `scrollComponentToVisible(Component c)`
  Scrolls so that the given component becomes visible.
  `void`
  `setCurrentInputDevice(VirtualInputDevice device)`
  Opens a virtual input device, closing whichever one was open before it.
  `void`
  `setCyclicFocus(boolean cyclicFocus)`
  Sets whether focus traversal wraps around at the edges.
  `void`
  `setEnableCursors(boolean e)`
  Sets whether components may change the mouse cursor.
  `void`
  `setFocused(Component focused)`
  Moves focus to the given component.
  `void`
  `setGlassPane(Painter glassPane)`
  Sets the painter drawn above everything else in this top level.
  `void`
  `setTintColor(int tintColor)`
  Sets the colour painted over this top level while a dialog or menu covers it.
  `void`
  `setTitle(String title)`
  Sets the title text.
  `void`
  `setUIManager(UIManager uiManager)`
  Sets the theme manager used to style this top level.
  `void`
  `show()`
  Makes this top level visible.
  `void`
  `stopEditing(Runnable onFinish)`
  Stops the in-progress edit and invokes the callback once it has finished.

- ## Method Details

  - ### addComponentAwaitingRelease

    <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`.

    ###### 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.

    ###### Parameters

    - `c`: the component awaiting a release

  - ### removeComponentAwaitingRelease

    <C extends Component> void removeComponentAwaitingRelease(C c)

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

    ###### Parameters

    - `c`: the component to stop tracking

  - ### clearComponentsAwaitingRelease

    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

    Container asContainer()

  - ### getContentPane

    Container getContentPane()

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

    ###### Returns

    the content pane

  - ### getLayeredPane

    Container getLayeredPane()

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

    ###### Returns

    the layered pane

  - ### getLayeredPane

    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`: the class owning the layer

    - `top`: true to place the layer above the existing layers

    ###### Returns

    the layer for the given class

  - ### getLayeredPane

    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`: the class owning the layer

    - `zIndex`: the depth at which the layer should sit

    ###### Returns

    the layer for the given class

  - ### getFormLayeredPane

    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`: the class owning the layer

    - `top`: true to place the layer above the existing layers

    ###### Returns

    the layer for the given class

  - ### getGlassPane

    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

    void setGlassPane(Painter glassPane)

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

    ###### Parameters

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

  - ### getTitle

    String getTitle()

    Returns the title text.

    ###### Returns

    the title

  - ### setTitle

    void setTitle(String title)

    Sets the title text.

    ###### Parameters

    - `title`: the title to display

  - ### addCommand

    void addCommand(Command cmd)

    Adds a command to this top level.

    ###### Parameters

    - `cmd`: the command to add

  - ### removeCommand

    void removeCommand(Command cmd)

    Removes a command from this top level.

    ###### Parameters

    - `cmd`: the command to remove

  - ### removeAllCommands

    void removeAllCommands()
    Removes every command from this top level.

  - ### getCommandCount

    int getCommandCount()

    Returns the number of commands.

    ###### Returns

    the command count

  - ### getCommand

    Command getCommand(int index)

    Returns the command at the given offset.

    ###### Parameters

    - `index`: the offset of the command

    ###### Returns

    the command at that offset

  - ### addCommandListener

    void addCommandListener(ActionListener l)

    Adds a listener notified when a command is activated.

    ###### Parameters

    - `l`: the listener to add

  - ### removeCommandListener

    void removeCommandListener(ActionListener l)

    Removes a previously added command listener.

    ###### Parameters

    - `l`: the listener to remove

  - ### getAnimationManager

    AnimationManager getAnimationManager()

    Returns the animation manager coordinating mutations of this top level.

    ###### Returns

    the animation manager

  - ### registerAnimated

    void registerAnimated(Animation cmp)

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

    ###### Parameters

    - `cmp`: the animation to register

  - ### deregisterAnimated

    void deregisterAnimated(Animation cmp)

    Removes a previously registered animation.

    ###### Parameters

    - `cmp`: the animation to remove

  - ### grabAnimationLock

    boolean grabAnimationLock()

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

    ###### Returns

    true if the lock was taken

  - ### releaseAnimationLock

    void releaseAnimationLock()
    Releases a previously taken animation lock.

  - ### getFocused

    Component getFocused()

    Returns the component currently owning focus.

    ###### Returns

    the focus owner, or null when nothing is focused

  - ### setFocused

    void setFocused(Component focused)

    Moves focus to the given component.

    ###### Parameters

    - `focused`: the component that should take focus

  - ### isCyclicFocus

    boolean isCyclicFocus()

    Returns true when focus traversal wraps around at the edges.

    ###### Returns

    true if focus is cyclic

  - ### setCyclicFocus

    void setCyclicFocus(boolean cyclicFocus)

    Sets whether focus traversal wraps around at the edges.

    ###### Parameters

    - `cyclicFocus`: true to make focus cyclic

  - ### isSingleFocusMode

    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

    Form.TabIterator getTabIterator(Component start)

    Returns an iterator walking the components in traversal order.

    ###### Parameters

    - `start`: the component to start from

    ###### Returns

    the traversal iterator

  - ### scrollComponentToVisible

    void scrollComponentToVisible(Component c)

    Scrolls so that the given component becomes visible.

    ###### Parameters

    - `c`: the component to reveal

  - ### addKeyListener

    void addKeyListener(int keyCode, ActionListener listener)

    Adds a key binding scoped to this top level.

    ###### Parameters

    - `keyCode`: the key code to bind

    - `listener`: the listener invoked for that key

  - ### removeKeyListener

    void removeKeyListener(int keyCode, ActionListener listener)

    Removes a previously added key binding.

    ###### Parameters

    - `keyCode`: the bound key code

    - `listener`: the listener to remove

  - ### isEditing

    boolean isEditing()

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

    ###### Returns

    true if editing is in progress

  - ### stopEditing

    void stopEditing(Runnable onFinish)

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

    ###### Parameters

    - `onFinish`: invoked once editing has stopped

  - ### findCurrentlyEditingComponent

    Component findCurrentlyEditingComponent()

    Returns the component currently being edited.

    ###### Returns

    the edited component, or null when nothing is being edited

  - ### getCurrentInputDevice

    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

    void setCurrentInputDevice(VirtualInputDevice device) throws Exception

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

    ###### Parameters

    - `device`: the device to open, or null to close the current one

    ###### Throws

    - `Exception`: if the previously open device failed to close
    Throws:
      `Exception`

  - ### getUIManager

    UIManager getUIManager()

    Returns the theme manager used to style this top level.

    ###### Returns

    the UI manager

  - ### setUIManager

    void setUIManager(UIManager uiManager)

    Sets the theme manager used to style this top level.

    ###### Parameters

    - `uiManager`: the UI manager to use

  - ### getTintColor

    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.

    ###### Returns

    the tint colour

  - ### setTintColor

    void setTintColor(int tintColor)

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

    ###### Parameters

    - `tintColor`: the tint colour, alpha in the high byte

  - ### isTopLevelShowing

    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

    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

    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

    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`: the x coordinate

    - `y`: the y coordinate

    ###### Returns

    the drag region status for that coordinate

  - ### isEnableCursors

    boolean isEnableCursors()

    Returns true when components may change the mouse cursor.

    ###### Returns

    true if cursors are enabled

  - ### setEnableCursors

    void setEnableCursors(boolean e)

    Sets whether components may change the mouse cursor.

    ###### Parameters

    - `e`: true to enable cursors

  - ### getTextSelection

    TextSelection getTextSelection()

    Returns the text selection support for this top level.

    ###### Returns

    the text selection

  - ### show

    void show()
    Makes this top level visible.

  - ### addShowListener

    void addShowListener(ActionListener l)

    Adds a listener notified whenever this top level is shown.

    ###### Parameters

    - `l`: the listener to add

  - ### removeShowListener

    void removeShowListener(ActionListener l)

    Removes a previously added show listener.

    ###### Parameters

    - `l`: the listener to remove

  - ### addSizeChangedListener

    void addSizeChangedListener(ActionListener l)

    Adds a listener notified whenever this top level changes size.

    ###### Parameters

    - `l`: the listener to add

  - ### removeSizeChangedListener

    void removeSizeChangedListener(ActionListener l)

    Removes a previously added size changed listener.

    ###### Parameters

    - `l`: the listener to remove

  - ### dispatchCommand

    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`: the command to dispatch

    - `ev`: the event to dispatch