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.

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

    • getTitleArea

      Container getTitleArea()

      Returns the area reserved for the title and its surrounding chrome.

      Returns

      the title area container

    • 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

    • getToolbar

      Toolbar getToolbar()

      Returns the toolbar installed in this top level.

      Returns

      the toolbar, or null when none is installed

    • setToolbar

      void setToolbar(Toolbar toolbar)

      Installs a toolbar in this top level.

      Parameters
      • toolbar: the toolbar to install

    • 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

    • 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