Class Container

java.lang.Object
com.codename1.ui.Component
com.codename1.ui.Container
All Implemented Interfaces:
Animation, Editable, StyleListener, Iterable<Component>
Direct Known Subclasses:
Accordion, Ads, AudioRecorderComponent, BaseSpinner, BrowserComponent, ButtonList, Calendar, ClearableTextField, ComponentGroup, ContainerList, EmbeddedContainer, FloatingHint, Form, HTMLComponent, InfiniteContainer, InputComponent, InteractionDialog, InterFormContainer, MapComponent, MediaPlayer, MenuBar, MultiButton, OnOffSwitch, Scene, Sheet, SignatureComponent, SpanButton, SpanLabel, SpanMultiButton, SplitPane, SwipeableContainer, Table, Tabs, TestRunnerComponent, Toolbar, Tree, WebBrowser
public class Container extends Component implements Iterable<Component>

A composite pattern with Component, allows nesting and arranging multiple components using a pluggable layout manager architecture. Containers can be nested one within the other to form elaborate UI's. By default Containers use com.codename1.ui.layouts.FlowLayout which isn't ideal for most use cases.

Components within the Container MUST be arranged using a layout manager!

This allows the UI to adapt to different resolutions, DPI, orientation changes etc. seamlessly. Invoking any bounds setting method will produce unpredictable results. To learn about layout managers check out the relevant section in the developer guide.

A container doesn't implicitly reflow its elements and in that regard follows the direction of AWT/Swing. As a result the layout can be animated to create a flowing effect for UI changes. This also provides improved performance as a bonus. See this sample of Container animation:

Form hi = new Form("Layout Animations", new BoxLayout(BoxLayout.Y_AXIS));
Button fall = new Button("Fall");
fall.addActionListener((e) -> {
    for(int iter = 0 ; iter < 10 ; iter++) {
        Label b = new Label ("Label " + iter);
        b.setWidth(fall.getWidth());
        b.setHeight(fall.getHeight());
        b.setY(-fall.getHeight());
        hi.add(b);
    }
    hi.getContentPane().animateLayout(20000);
});
hi.add(fall);

Many components within Codename One (e.g. com.codename1.ui.tree.Tree, com.codename1.ui.table.Table, com.codename1.components.MultiButton etc.) derive from Container instead of Component. This allows such components to provide very rich functionality by building on top of the existing functionality. Container also provides the lead component functionality that allows treating an entire Container hierarchy as a single component. This is discussed in depth within the developer guide.

  • Constructor Details

    • Container

      public Container(Layout layout, String uiid)

      Constructs a new Container with a new layout manager and UIID

      Parameters

      • layout: the specified layout manager

      • uiid: the uiid of the container

    • Container

      public Container(Layout layout)

      Constructs a new Container with a new layout manager.

      Parameters
      • layout: the specified layout manager

    • Container

      public Container()
      Constructs a new Container, with a FlowLayout.

  • Method Details

    • encloseIn

      public static Container encloseIn(Layout l, Component cmp, Object cons)

      Short-hand for enclosing a component within a Container

      Parameters

      • l: the layout

      • cmp: the component to enclose

      • cons: the constraint for the component

      Returns

      a newly created container containing the given component

    • encloseIn

      public static Container encloseIn(Layout l, Component... cmp)

      Short-hand for enclosing multiple components in a container typically a box layout

      Parameters

      • l: the layout

      • cmp: the components to enclose

      Returns

      a newly created container containing the given components

    • initLaf

      protected void initLaf(UIManager uim)
      This method initializes the Component defaults constants
      Overrides:
      initLaf in class Component

    • getUIManager

      public UIManager getUIManager()

      This method should be used by the Component to retrieve the correct UIManager to work with

      Returns

      a UIManager instance

      Overrides:
      getUIManager in class Component

    • setUIManager

      public void setUIManager(UIManager uiManager)

      Allows replacing the UIManager in a component hierarchy to update the look and feel only to a specific hierarchy

      Parameters
      • uiManager: UIManager instance

    • isSurface

      public boolean isSurface()

      Checks if this container acts as a Material Design surface. "Surface" containers render drop-shadows for their elevated descendents.

      Returns

      True if this container is a surface.

      Since

      8.0

    • add

      public final Container add(Component cmp)

      Simpler version of addComponent that allows chaining the calls for shorter syntax

      Parameters
      • cmp: the component to add
      Returns

      this for call chaining

    • addAll

      public Container addAll(Component... cmps)

      Identical to add(x).add(y) only with a shorter syntax

      Parameters
      • cmps: the other components to add
      Returns

      this for call chaining

    • add

      public Container add(Object constraint, Component cmp)

      Simpler version of addComponent that allows chaining the calls for shorter syntax

      Parameters

      • constraint: the layout constraint if applicable

      • cmp: the component to add

      Returns

      this for call chaining

    • add

      public Container add(String label)

      Simpler version of addComponent that allows chaining the calls for shorter syntax

      Parameters
      • label: a string that will be wrapped as a label, this is equivalent to calling add(new Label(l))
      Returns

      this for call chaining

    • add

      public Container add(Image img)

      Simpler version of addComponent that allows chaining the calls for shorter syntax

      Parameters
      • img: an image that will be wrapped as a label, this is equivalent to calling add(new Label(l))
      Returns

      this for call chaining

    • add

      public Container add(Object constraint, String label)

      Simpler version of addComponent that allows chaining the calls for shorter syntax

      Parameters

      • constraint: the layout constraint if applicable

      • label: a component that will be wrapped as a label, this is equivalent to calling add(new Label(l))

      Returns

      this for call chaining

    • add

      public Container add(Object constraint, Image img)

      Simpler version of addComponent that allows chaining the calls for shorter syntax

      Parameters

      • constraint: the layout constraint if applicable

      • img: an image that will be wrapped as a label, this is equivalent to calling add(new Label(l))

      Returns

      this for call chaining

    • getLeadComponent

      public Component getLeadComponent()

      Returns the lead component for this hierarchy if such a component is defined

      Returns

      the lead component

    • setLeadComponent

      public final void setLeadComponent(Component lead)

      Sets the lead component for this container, a lead component takes over the entire component hierarchy and receives all the events for the container hierarchy.

      Parameters
      • lead: component that takes over the hierarchy

    • getLeadParent

      public Container getLeadParent()

      Returns the lead container thats handling the leading, this is useful for a container hierarchy where the parent container might not be the leader

      Returns

      the lead component

    • keyPressed

      public void keyPressed(int k)

      If this Component is focused, the key pressed event will call this method

      Parameters
      • keyCode: the key code value to indicate a physical key.
      Overrides:
      keyPressed in class Component

    • keyReleased

      public void keyReleased(int k)

      If this Component is focused, the key released event will call this method

      Parameters
      • keyCode: the key code value to indicate a physical key.
      Overrides:
      keyReleased in class Component

    • getLayout

      public Layout getLayout()

      Returns the layout manager responsible for arranging this container.

      Returns

      the container layout manager

    • setLayout

      public void setLayout(Layout layout)

      Sets the layout manager responsible for arranging this container

      Parameters
      • layout: the specified layout manager

    • invalidate

      public void invalidate()
      Same as setShouldCalcPreferredSize(true) but made accessible for layout managers

    • setShouldLayout

      protected void setShouldLayout(boolean layout)

      Flags this container to preform layout

      Parameters
      • layout

    • setShouldCalcPreferredSize

      public void setShouldCalcPreferredSize(boolean shouldCalcPreferredSize)

      Indicates the values within the component have changed and preferred size should be recalculated

      Parameters
      • shouldCalcPreferredSize: @param shouldCalcPreferredSize indicate whether this component need to recalculate his preferred size
      Overrides:
      setShouldCalcPreferredSize in class Component

    • getLayoutWidth

      public int getLayoutWidth()

      Returns the width for layout manager purposes, this takes scrolling into consideration unlike the getWidth method.

      Returns

      the layout width

    • getLayoutHeight

      public int getLayoutHeight()

      Returns the height for layout manager purposes, this takes scrolling into consideration unlike the getHeight method.

      Returns

      the layout height

    • applyRTL

      public void applyRTL(boolean rtl)

      Invokes apply/setRTL recursively on all the children components of this container

      Parameters
      • rtl: right to left bidi indication
      See also
      • Component#setRTL(boolean)

    • constrainWidthWhenScrollable

      protected boolean constrainWidthWhenScrollable()

      Indicates that children's widths should be calculated as if this component weren't scrollable-X, even when the component is scrollable X. Normally, when a component is figuring out its layout width, it will walk up the UI hierarchy to find the first scrollable container. If there is a scrollable container, then the component will try to grow as big as it wants. If there are no scrollable containers found, it will constrain itself to the space available. In some cases, we may want the children of a component to lay themselves out conservatively though because it wants to use its scrollability for other features.

      Returns
      Returns:

      True if children should calculate their layout widgets as if the component weren't scrollable.

      Since

      7.0

    • constrainHeightWhenScrollable

      protected boolean constrainHeightWhenScrollable()

      Indicates that children's widths should be calculated as if this component weren't scrollable-X, even when the component is scrollable Y. Normally, when a component is figuring out its layout width, it will walk up the UI hierarchy to find the first scrollable container. If there is a scrollable container, then the component will try to grow as big as it wants. If there are no scrollable containers found, it will constrain itself to the space available. In some cases, we may want the children of a component to lay themselves out conservatively though because it wants to use its scrollability for other features.

      Returns
      Returns:

      True if children should calculate their layout widgets as if the component weren't scrollable.

      Since

      7.0

    • addComponent

      public void addComponent(Component cmp)

      Adds a Component to the Container

      Parameters
      • cmp: the component to be added

    • addComponent

      public void addComponent(Object constraints, Component cmp)

      Adds a Component to the Container

      Parameters

      • constraints: @param constraints this method is useful when the Layout requires a constraint such as the BorderLayout. In this case you need to specify an additional data when you add a Component, such as "CENTER", "NORTH"...

      • cmp: component to add

    • addComponent

      public void addComponent(int index, Object constraints, Component cmp)

      Adds a Component to the Container

      Parameters

      • index: location to insert the Component

      • constraints: @param constraints this method is useful when the Layout requires a constraint such as the BorderLayout. In this case you need to specify an additional data when you add a Component, such as "CENTER", "NORTH"...

      • cmp: component to add

    • addComponent

      public void addComponent(int index, Component cmp)

      This method adds the Component at a specific index location in the Container Components array.

      Parameters

      • index: location to insert the Component

      • cmp: the Component to add

      Throws

      • ArrayIndexOutOfBoundsException: if index is out of bounds

      • IllegalArgumentException: @throws IllegalArgumentException if Component is already contained or the cmp is a Form Component

    • replaceAndWait

      public void replaceAndWait(Component current, Component next, Transition t)

      This method replaces the current Component with the next Component. Current Component must be contained in this Container. This method returns when transition has finished.

      Parameters

      • current: a Component to remove from the Container

      • next: a Component that replaces the current Component

      • t: @param t a Transition between the add and removal of the Components a Transition can be null

    • replaceAndWait

      public void replaceAndWait(Component current, Component next, Transition t, int layoutAnimationSpeed)

      This method replaces the current Component with the next Component. Current Component must be contained in this Container. This method returns when transition has finished.

      Parameters

      • current: a Component to remove from the Container

      • next: a Component that replaces the current Component

      • t: @param t a Transition between the add and removal of the Components a Transition can be null

      • layoutAnimationSpeed: the speed of the layout animation after replace is completed

    • replace

      public void replace(Component current, Component next, Transition t, Runnable onFinish, int growSpeed)

      This method replaces the current Component with the next Component

      Parameters

      • current: a Component to remove from the Container

      • next: a Component that replaces the current Component

      • t: @param t a Transition between the add and removal of the Components a Transition can be null

      • onFinish: invoked when the replace operation is completed, may be null

      • growSpeed: @param growSpeed after replace is completed the component can gradually grow/shrink to fill up available room, set this to 0 for immediate growth or any larger number for gradual animation. -1 indicates a special case where no validation occurs

    • replaceAndWait

      public void replaceAndWait(Component current, Component next, Transition t, boolean dropEvents)

      This method replaces the current Component with the next Component. Current Component must be contained in this Container. This method returns when transition has finished.

      Parameters

      • current: a Component to remove from the Container

      • next: a Component that replaces the current Component

      • t: @param t a Transition between the add and removal of the Components a Transition can be null

      • dropEvents: @param dropEvents indicates if the display should drop all events while this Component replacing is happening

    • replace

      public void replace(Component current, Component next, Transition t)

      This method replaces the current Component with the next Component. Current Component must be contained in this Container. This method return immediately.

      Parameters

      • current: a Component to remove from the Container

      • next: a Component that replaces the current Component

      • t: @param t a Transition between the add and removal of the Components a Transition can be null

    • createReplaceTransition

      public ComponentAnimation createReplaceTransition(Component current, Component next, Transition t)

      This method creates an animation component that replaces the current Component with the next Component. Current Component must be contained in this Container. This method return immediately.

      Parameters

      • current: a Component to remove from the Container

      • next: a Component that replaces the current Component

      • t: @param t a Transition between the add and removal of the Components a Transition can be null

      Returns

      animation component that can be queued

    • isEnabled

      public boolean isEnabled()

      Indicates whether component is enabled or disabled thus allowing us to prevent a component from receiving input events and indicate so visually

      Returns

      true if enabled

      Overrides:
      isEnabled in class Component

    • setEnabled

      public void setEnabled(boolean enabled)

      This method will recursively set all the Container chidrens to be enabled/disabled. If the Container is disabled and a child Component changed it's state to be enabled, the child Component will be treated as an enabled Component.

      Parameters
      • enabled
      Overrides:
      setEnabled in class Component

    • removeComponent

      public void removeComponent(Component cmp)

      removes a Component from the Container, notice that removed component might still have a pending repaint in the queue that won't be removed. Calling form.repaint() will workaround such an issue.

      Parameters
      • cmp: the removed component

    • cancelRepaints

      protected void cancelRepaints()
      remove this component and it's children from the painting queue
      Overrides:
      cancelRepaints in class Component

    • flushReplace

      public void flushReplace()

      Flushes ongoing replace operations to prevent two concurrent replace operations from colliding. If there is no ongoing replace nothing will occur

      Deprecated

      this method is no longer used in the new animation framework

    • removeAll

      public void removeAll()
      remove all Components from container, notice that removed component might still have a pending repaint in the queue that won't be removed. Calling form.repaint() will workaround such an issue. Notice that this method doesn't recurse and only removes from the current container.

    • revalidateWithAnimationSafety

      public void revalidateWithAnimationSafety()

      Revalidates the container in a way that doesn't conflict with running animations. If you simply call #revalidate() on a container while an animation is in progress, it will produce paint artifacts as it will insert frames in the animation with the container at its final position. Using this method, it will wait until running animations are complete before it revalidates.

      Since

      6.0

    • revalidate

      public void revalidate()
      Re-layout the container, this is useful when we modify the container hierarchy and need to redo the layout

    • revalidateLater

      public void revalidateLater()
      Revalidates the container before the next paint cycle. Prefer this method to #revalidate() and #revalidateWithAnimationSafety() if you don't need the revalidate (layout and repaint) to happen immediately, but you do want it to happen before the next paint. This is can be far more efficient as it will squash the revalidation calls into the minimal set of containers that require revalidation, so that the system doesn't end up revalidating the same container multiple times between paints.

    • forceRevalidate

      public void forceRevalidate()
      A more powerful form of revalidate that recursively lays out the full hierarchy

    • clearClientProperties

      public void clearClientProperties()
      Clears all client properties from this Component
      Overrides:
      clearClientProperties in class Component

    • paint

      public void paint(Graphics g)

      This method paints the Component on the screen, it should be overriden by subclasses to perform custom drawing or invoke the UI API's to let the PLAF perform the rendering.

      Parameters
      • g: the component graphics
      Specified by:
      paint in interface Animation
      Overrides:
      paint in class Component

    • paintGlass

      protected void paintGlass(Graphics g)

      This method can be overriden by a component to draw on top of itself or its children after the component or the children finished drawing in a similar way to the glass pane but more refined per component

      Parameters
      • g: the graphics context

    • layoutContainer

      public void layoutContainer()
      Performs the layout of the container if a layout is necessary

    • isSafeArea

      public boolean isSafeArea()

      Checks if this container is a "safe area". A "safe area" is a container whose contents will always be displayed inside the device's "safe display area".

      This feature was added primarily for the iPhone X which covers some parts of the screen and would cover or interfere with any content drawn in those regions. In particular, the notch, the rounded corners, and the task bar cover portions of the screen.

      A container that is a safe area will automatically add appropriate padding on layout so that its children will be rendered completely in the safe area of the screen. This only applies if the container has no scrollable parents. If a "safe" container has scrollable parents, then it is assumed that the user can just scroll it into a safe area.

      Returns

      True if this container is a safe area.

      Since

      7.0

      See also

      • #setSafeArea(boolean)

      • Form#getSafeArea()

    • setSafeArea

      public void setSafeArea(boolean safeArea)

      Marks this container as a "safe area", meaning that it will automatically supply sufficient padding as necessary for its children to be laid out inside the safe area of the screen.

      This was primarily added for the iPhone X which covers portions of the screen and may interfere with components that are rendered there.

      The "safe" area is calculated against a "safe area root"'s bounds, which is the parent form by default. In some cases it may be helpful to make the root a sub-container, such as if you need to lay a component out off-screen. See #setSafeAreaRoot(boolean) for more details.

      Parameters
      • safeArea: True to make this container a safe area.
      Since

      7.0

      See also

      • Form#getSafeArea()

      • #isSafeArea()

      • #setSafeAreaRoot(boolean)

    • isSafeAreaRoot

      public boolean isSafeAreaRoot()

      Checks if this container is a safe area root. A safe area root is a container against whose bounds, safe area margins are calculated for child components.

      Forms are safe area roots by default.

      Since

      7.0

      See also
      • #setSafeAreaRoot(boolean)

    • getSafeAreaRoot

      public Container getSafeAreaRoot()

      Gets the Safe area "root" container for this container. This method will walk up the component hierarchy until is finds a Container with #isSafeAreaRoot() true.

      Forms are safe area roots by default, but it is possible to mark other containers as safe area roots.

      A safe area root is a container from which safe area margins are applied when calculating the safe areas of child components. Setting a root can facilitate the layout of a container's children before it appears on the screen.

      Since

      7.0

    • setSafeAreaRoot

      public void setSafeAreaRoot(boolean root)

      Set whether this container is a safe area root. A safe area root is a container against whose bounds, safe area margins are calculated for child components.

      Safe Area root vs Safe Area

      A Safe Area root is not actually a safe area. It will lay out its children normally, without any adjustments to padding to accommodate the display safe area. They are rather used by safe area child containers to calculate safe area margins, according to if the safe area root container spanned the entire screen

      In most cases you don't need to explicitly set a safe area root, since Forms are marked as roots by default. However, there are edge cases where components may be initially laid out off-screen (in which safe areas are not applied), but are transitioned in. Once on the screen, the safe margins would be applied which may cause an abrupt re-layout at the moment that the safe margins are applied. This edge case occurs in, for example, a side menu bar which is rendered off-screen. By making the side menu bar container a "root" itself, the safe areas will be applied to the layout, even when the menu is off-screen. Then there is no "jerk" when it transitions in.

      Parameters
      • root: True to make this a root. False to make it "not" a root.
      Since

      7.0

      See also
      • #isSafeAreaRoot()

    • getComponentCount

      public int getComponentCount()

      Returns the number of components

      Returns

      the Component count

    • getComponentAt

      public Component getComponentAt(int index)

      Returns the Component at a given index

      Parameters
      • index: of the Component you wish to get
      Returns

      a Component

      Throws
      • ArrayIndexOutOfBoundsException: if an invalid index was given.

    • getComponentIndex

      public int getComponentIndex(Component cmp)

      Returns the Component index in the Container

      Parameters
      • cmp: the component to search for
      Returns

      the Component index in the Container or -1 if not found

    • contains

      public boolean contains(Component cmp)

      Returns true if the given component is within the hierarchy of this container

      Parameters
      • cmp: a Component to check
      Returns

      true if this Component contains in this Container

    • scrollComponentToVisible

      public void scrollComponentToVisible(Component c)

      Makes sure the component is visible in the scroll if this container is scrollable

      Parameters
      • c: the component that will be scrolling for visibility

    • getClosestComponentTo

      public Component getClosestComponentTo(int x, int y)

      Very useful for touch events or drop events that need approximation more than accuracy

      Parameters

      • x: location in container relative coordinates

      • y: location in container relative coordinates

      Returns

      the closest component in the container or null if no component is in the container

    • getResponderAt

      public Component getResponderAt(int x, int y)

      Returns the top-most component that responds to pointer events at absolute coordinate (x, y). This may return null if there are no components at this coordinate that respond to pointer events.

      Note: This method is stricter than int) about which component is returned. Whereas int) will return this when there are no matches, as long as it contains (x, y), int) will return null in this case. int) may also return components that are not visible or are not enabled. In generaly, if you are trying to retrieve a component that responds to pointer events, you should use this method over int) unless you have a good reason and really know what you are doing.

      Parameters

      • x: Absolute x-coordinate.

      • y: Absolute y-coordinate.

      Returns

      Top-most component that responds to pointer events at given coordinate. May be null.

      See also
      • Component#respondsToPointerEvents()

    • getComponentAt

      public Component getComponentAt(int x, int y)

      Returns a Component at coordinate (x, y).

      WARNING: This method may return components that are disabled, or invisible, or that do not respond to pointer events. If you are looking for the top-most component that responds to pointer events, you should use int) as it is guaranteed to return a component with Component#respondsToPointerEvents() true; or null if none is found at the coordinate.

      Parameters

      • x: absolute screen location

      • y: absolute screen location

      Returns

      a Component if found, null otherwise

      See also

      • Component#contains

      • #getResponderAt(int, int)

    • findDropTargetAt

      public Component findDropTargetAt(int x, int y)

      Recursively searches the container hierarchy for a drop target

      Parameters

      • x: position in which we are searching for a drop target

      • y: position in which we are searching for a drop target

      Returns

      a drop target or null if no drop target could be found at the x/y position

    • pointerPressed

      public void pointerPressed(int x, int y)

      If this Component is focused, the pointer pressed event will call this method

      Parameters

      • x: the pointer x coordinate

      • y: the pointer y coordinate

      Overrides:
      pointerPressed in class Component

    • calcPreferredSize

      protected Dimension calcPreferredSize()

      Calculates the preferred size based on component content. This method is invoked lazily by getPreferred size.

      Returns

      the calculated preferred size based on component content

      Overrides:
      calcPreferredSize in class Component

    • paramString

      protected String paramString()

      Returns a string representing the state of this component. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

      Returns

      a string representation of this component's state

      Overrides:
      paramString in class Component

    • refreshTheme

      public void refreshTheme(boolean merge)

      Makes sure the component is up to date with the current theme, ONLY INVOKE THIS METHOD IF YOU CHANGED THE THEME!

      Parameters
      • merge: indicates if the current styles should be merged with the new styles
      Overrides:
      refreshTheme in class Component

    • isScrollableX

      public boolean isScrollableX()

      Indicates whether the component should/could scroll on the X axis

      Returns

      whether the component is scrollable on the X axis

      Overrides:
      isScrollableX in class Component

    • setScrollableX

      public void setScrollableX(boolean scrollableX)

      Sets whether the component should/could scroll on the X axis

      Parameters
      • scrollableX: whether the component should/could scroll on the X axis

    • isScrollableY

      public boolean isScrollableY()

      Indicates whether the component should/could scroll on the Y axis

      Returns

      whether the component is scrollable on the X axis

      Overrides:
      isScrollableY in class Component

    • setScrollableY

      public void setScrollableY(boolean scrollableY)

      Sets whether the component should/could scroll on the Y axis

      Parameters
      • scrollableY: whether the component should/could scroll on the Y axis

    • getSideGap

      public int getSideGap()

      Returns the gap to be left for the side scrollbar on the Y axis. This method is used by layout managers to determine the room they should leave for the scrollbar. (note: side scrollbar rather than left scrollbar is used for a future version that would support bidi).

      Returns

      the gap to be left for the side scrollbar on the Y axis

      Overrides:
      getSideGap in class Component

    • getBottomGap

      public int getBottomGap()

      Returns the gap to be left for the bottom scrollbar on the X axis. This method is used by layout managers to determine the room they should leave for the scrollbar

      Returns

      the gap to be left for the bottom scrollbar on the X axis

      Overrides:
      getBottomGap in class Component

    • setScrollable

      public void setScrollable(boolean scrollable)

      The equivalent of calling both setScrollableY and setScrollableX

      Parameters
      • scrollable: @param scrollable whether the component should/could scroll on the X and Y axis
      Deprecated

      use setScrollableX and setScrollableY instead. This method is deprecated since it breeds confusion and is often misunderstood.

    • setCellRenderer

      public void setCellRenderer(boolean cellRenderer)

      Used as an optimization to mark that this component is currently being used as a cell renderer

      Parameters
      • cellRenderer: @param cellRenderer indicate whether this component is currently being used as a cell renderer
      Overrides:
      setCellRenderer in class Component

    • getScrollIncrement

      public int getScrollIncrement()

      Gets the Container scroll increment

      Returns

      the scroll increment in pixels.

    • setScrollIncrement

      public void setScrollIncrement(int scrollIncrement)

      Determines the scroll increment size of this Container. This value is in use when the current foucs element within this Container is larger than this Container size.

      Parameters
      • scrollIncrement: the size in pixels.

    • findFirstFocusable

      public Component findFirstFocusable()

      Finds the first focusable Component on this Container

      Returns

      a focusable Component or null if not exists;

    • dragInitiated

      protected void dragInitiated()
      Invoked on the focus component to let it know that drag has started on the parent container for the case of a component that doesn't support scrolling
      Overrides:
      dragInitiated in class Component

    • fireClicked

      protected void fireClicked()
      When working in 3 softbutton mode "fire" key (center softbutton) is sent to this method in order to allow 3 button devices to work properly. When overriding this method you should also override isSelectableInteraction to indicate that a command is placed appropriately on top of the fire key for 3 soft button phones.
      Overrides:
      fireClicked in class Component

    • isSelectableInteraction

      protected boolean isSelectableInteraction()

      This method allows a component to indicate that it is interested in an "implicit" select command to appear in the "fire" button when 3 softbuttons are defined in a device.

      Returns

      true if this is a selectable interaction

      Overrides:
      isSelectableInteraction in class Component

    • getGridPosY

      protected int getGridPosY()

      This method should be implemented correctly by subclasses to make snap to grid functionality work as expected. Returns the ideal grid Y position closest to the current Y position.

      Returns

      a valid Y position in the grid

      Overrides:
      getGridPosY in class Component

    • paintComponentBackground

      public void paintComponentBackground(Graphics g)

    • getGridPosX

      protected int getGridPosX()

      This method should be implemented correctly by subclasses to make snap to grid functionality work as expected. Returns the ideal grid X position closest to the current X position.

      Returns

      a valid Y position in the grid

      Overrides:
      getGridPosX in class Component

    • animateHierarchyAndWait

      public void animateHierarchyAndWait(int duration)

      Animates a pending hierarchy of components into place, this effectively replaces revalidate with a more visual form of animation. This method waits until the operation is completed before returning

      Parameters
      • duration: the duration in milliseconds for the animation

    • createAnimateHierarchy

      public ComponentAnimation createAnimateHierarchy(int duration)

      Animates a pending hierarchy of components into place, this effectively replaces revalidate with a more visual form of animation.

      Parameters
      • duration: the duration in milliseconds for the animation
      Returns

      the animation object that should be added to the animation manager

    • animateHierarchy

      public void animateHierarchy(int duration)

      Animates a pending hierarchy of components into place, this effectively replaces revalidate with a more visual form of animation

      Parameters
      • duration: the duration in milliseconds for the animation

    • animateHierarchyFadeAndWait

      public void animateHierarchyFadeAndWait(int duration, int startingOpacity)

      Animates a pending hierarchy of components into place, this effectively replaces revalidate with a more visual form of animation. This method waits until the operation is completed before returning

      Parameters

      • duration: the duration in milliseconds for the animation

      • startingOpacity: the initial opacity to give to the animated components

    • createAnimateHierarchyFade

      public ComponentAnimation createAnimateHierarchyFade(int duration, int startingOpacity)

      Animates a pending hierarchy of components into place, this effectively replaces revalidate with a more visual form of animation.

      Parameters

      • duration: the duration in milliseconds for the animation

      • startingOpacity: the initial opacity to give to the animated components

      Returns

      the animation object that should be added to the animation manager

    • animateHierarchyFade

      public void animateHierarchyFade(int duration, int startingOpacity)

      Animates a pending hierarchy of components into place, this effectively replaces revalidate with a more visual form of animation

      Parameters

      • duration: the duration in milliseconds for the animation

      • startingOpacity: the initial opacity to give to the animated components

    • animateLayoutFadeAndWait

      public void animateLayoutFadeAndWait(int duration, int startingOpacity)

      Animates a pending layout into place, this effectively replaces revalidate with a more visual form of animation. This method waits until the operation is completed before returning

      Parameters

      • duration: the duration in milliseconds for the animation

      • startingOpacity: the initial opacity to give to the animated components

    • createAnimateLayoutFadeAndWait

      public ComponentAnimation createAnimateLayoutFadeAndWait(int duration, int startingOpacity)

      Animates a pending layout into place, this effectively replaces revalidate with a more visual form of animation. This method waits until the operation is completed before returning

      Parameters

      • duration: the duration in milliseconds for the animation

      • startingOpacity: the initial opacity to give to the animated components

      Returns

      the animation object that should be added to the animation manager

      Deprecated

      this was added by mistake!

    • animateLayoutFade

      public void animateLayoutFade(int duration, int startingOpacity)

      Animates a pending layout into place, this effectively replaces revalidate with a more visual form of animation

      Parameters

      • duration: the duration in milliseconds for the animation

      • startingOpacity: the initial opacity to give to the animated components

    • createAnimateLayoutFade

      public ComponentAnimation createAnimateLayoutFade(int duration, int startingOpacity)

      Animates a pending layout into place, this effectively replaces revalidate with a more visual form of animation

      Parameters

      • duration: the duration in milliseconds for the animation

      • startingOpacity: the initial opacity to give to the animated components

      Returns

      the animation object that should be added to the animation manager

    • animateLayoutAndWait

      public void animateLayoutAndWait(int duration)

      Animates a pending layout into place, this effectively replaces revalidate with a more visual form of animation. This method waits until the operation is completed before returning

      Parameters
      • duration: the duration in milliseconds for the animation

    • animateLayout

      public void animateLayout(int duration)

      Animates a pending layout into place, this effectively replaces revalidate with a more visual form of animation

      See:

      Form hi = new Form("Layout Animations", new BoxLayout(BoxLayout.Y_AXIS));
Button fall = new Button("Fall");
fall.addActionListener((e) -> {
    for(int iter = 0 ; iter < 10 ; iter++) {
        Label b = new Label ("Label " + iter);
        b.setWidth(fall.getWidth());
        b.setHeight(fall.getHeight());
        b.setY(-fall.getHeight());
        hi.add(b);
    }
    hi.getContentPane().animateLayout(20000);
});
hi.add(fall);
      Parameters
      • duration: the duration in milliseconds for the animation

    • updateTabIndices

      public int updateTabIndices(int offset)

      Updates the tab indices in this container recursively. This method is used internally by layout managers when calculating the traversal order of components in a form.

      Parameters
      • offset: The starting tab index.
      Returns

      The ending tab index (+1)

      Deprecated

      For internal use only.

    • createAnimateLayout

      public ComponentAnimation createAnimateLayout(int duration)

      Animates a pending layout into place, this effectively replaces revalidate with a more visual form of animation

      See:

      Form hi = new Form("Layout Animations", new BoxLayout(BoxLayout.Y_AXIS));
Button fall = new Button("Fall");
fall.addActionListener((e) -> {
    for(int iter = 0 ; iter < 10 ; iter++) {
        Label b = new Label ("Label " + iter);
        b.setWidth(fall.getWidth());
        b.setHeight(fall.getHeight());
        b.setY(-fall.getHeight());
        hi.add(b);
    }
    hi.getContentPane().animateLayout(20000);
});
hi.add(fall);
      Parameters
      • duration: the duration in milliseconds for the animation
      Returns

      the animation object that should be added to the animation manager

    • drop

      public void drop(Component dragged, int x, int y)

      Performs a drop operation of the component at the given X/Y location in coordinate space, this method should be overriden by subclasses to perform all of the logic related to moving a component, by default this method does nothing and so dragging a component and dropping it has no effect

      Parameters

      • dragged: the component being dropped

      • x: the x coordinate of the drop

      • y: the y coordinate of the drop

      Overrides:
      drop in class Component

    • createAnimateMotion

      protected Motion createAnimateMotion(int start, int destination, int duration)

      Creates a motion object for animation, allows subclasses to replace the motion type used in animations (currently defaults to ease-in).

      Parameters

      • start: start value

      • destination: destination value

      • duration: duration of animation

      Returns

      motion object

    • morph

      public void morph(Component source, Component destination, int duration, Runnable onCompletion)

      Morph is similar to the replace functionality where a component might be replaced with a component that isn't within the container. However, unlike the replace functionality which uses a transition and assumes the position of the component (and is hence quite flexible) morph can move and resize the component. E.g. after entering text into a text field and pressing submit it can "morph" into a chat bubble located in a different part of the screen.

      It is the responsibility of the caller to remove the source component (if desired) and revalidate the container when the animation completes.

      Parameters

      • source: source component assumed to be within this container or one of its children

      • destination: the destination component

      • duration: the time the morph operation should take

      • onCompletion: invoked when the morphing completes

    • morphAndWait

      public void morphAndWait(Component source, Component destination, int duration)

      Morph is similar to the replace functionality where a component might be replaced with a component that isn't within the container. However, unlike the replace functionality which uses a transition and assumes the position of the component (and is hence quite flexible) morph can move and resize the component. E.g. after entering text into a text field and pressing submit it can "morph" into a chat bubble located in a different part of the screen.

      It is the responsibility of the caller to remove the source component (if desired) and revalidate the container when the animation completes.

      Parameters

      • source: source component assumed to be within this container or one of its children

      • destination: the destination component

      • duration: the time the morph operation should take

    • animateUnlayout

      public void animateUnlayout(int duration, int opacity, Runnable callback)

      This method is the exact reverse of animateLayout, when completed it leaves the container in an invalid state. It is useful to invoke this in order to remove a component, transition to a different form or provide some other interaction. E.g.:

      Form hi = new Form("Layout Animations", new BoxLayout(BoxLayout.Y_AXIS));
Button fall = new Button("Fall");
fall.addActionListener((e) -> {
    if(hi.getContentPane().getComponentCount() == 1) {
        fall.setText("Rise");
        for(int iter = 0 ; iter  {
            hi.removeAll();
            hi.add(fall);
            hi.revalidate();
        });*/

    }
});
hi.add(fall);
      Parameters

      • duration: the duration of the animation

      • opacity: the opacity to which the layout will reach, allows fading out the components

      • callback: if not null will be invoked when unlayouting is complete

    • animateUnlayoutAndWait

      public void animateUnlayoutAndWait(int duration, int opacity)

      This method is the exact reverse of animateLayoutAndWait, when completed it leaves the container in an invalid state. It is useful to invoke this in order to remove a component, transition to a different form or provide some other interaction. E.g.:

      Form hi = new Form("Layout Animations", new BoxLayout(BoxLayout.Y_AXIS));
Button fall = new Button("Fall");
fall.addActionListener((e) -> {
    if(hi.getContentPane().getComponentCount() == 1) {
        fall.setText("Rise");
        for(int iter = 0 ; iter  {
            hi.removeAll();
            hi.add(fall);
            hi.revalidate();
        });*/

    }
});
hi.add(fall);
      Parameters

      • duration: the duration of the animation

      • opacity: the opacity to which the layout will reach, allows fading out the components

    • createAnimateUnlayout

      public ComponentAnimation createAnimateUnlayout(int duration, int opacity, Runnable callback)

      This method is the exact reverse of createAnimateLayout, when animation is completed it leaves the container in an invalid state. It is useful to invoke this in order to remove a component, transition to a different form or provide some other interaction. E.g.:

      Parameters

      • duration: the duration of the animation

      • opacity: the opacity to which the layout will reach, allows fading out the components

      Returns

      the animation object that should be added to the animation manager

    • getChildrenAsList

      public List<Component> getChildrenAsList(boolean includeQueued)

      Gets the child components of this Container as a List. Using true as the argument provides a way to obtain all of the children, including children whose full addition is pending while an animation is in progress.

      Animation Discussion: If children are added or removed from a Container while its containing Form has an animation in progress, the insertion/deletion isn't complete until after the animation is finished. Most methods to interact with a container's children won't see these pending changes until that time. E.g.:

      `// Assume an animation is in progress on the form containing cnt. Label lbl = new Label("Test"); int len = cnt.getComponentCount(); // 0 cnt.addComponent(lbl); int lenAfter = cnt.getComponentCount(); // 0 cnt.contains(lbl); // true cnt.getChildrenAsList(true).size(); // 1 cnt.getChildrenAsList(false).size(); // 0

      Button btn = new Button("Press me"); cnt.addComponent(btn); cnt.getComponentCount(); // 0 cnt.getChildrenAsList(true).size(); // 2 cnt.removeComponent(btn); cnt.getComponentCount(); // 0 cnt.getChildrenAsList(true).size(); // 1

      `

      Parameters
      • includeQueued: True to reflect queued inserts and removals while an animation is in progress.
      Returns

      A list including all of the children of this container.

      See also
      • #iterator(boolean)

    • iterator

      public Iterator<Component> iterator(boolean includeQueued)

      Obtains an iterator that iterates over the children of this container. If argument is true, then the iteratator will include queued insertions/deletions while an animation is in progress.

      Parameters
      • includeQueued: True to include queued component insertions and removals while animation is in progress.
      Returns

      An iterator that iterates over the children of this component.

      See also

      • #iterator()

      • #getChildrenAsList(boolean)

    • iterator

      public Iterator<Component> iterator()

      Part of the Iterable interface allowing us to do a for-each loop on Container

      Returns

      the iterator of the components

      Specified by:
      iterator in interface Iterable<Component>