public class Form

ImplementsAnimation, Editable, Iterable<Component>, StyleListener, TopLevelContainer

Known subtypesDialog

Top level component that serves as the root for the UI, this Container subclass works in concert with the Toolbar to create menus. By default a forms main content area (the content pane) is scrollable on the Y axis and has a com.codename1.ui.layouts.FlowLayout as is the default.

Form contains a title bar area which in newer application is replaced by the Toolbar. Calling #add(com.codename1.ui.Component) or all similar methods on the Form delegates to the contentPane so calling form.add(cmp) is equivalent to form.getContentPane().add(cmp). Normally this shouldn’t matter, however in some cases such as animation we need to use the content pane directly e.g. form.getContentPane().animateLayout(200) will work whereas form.animateLayout(200) will fail.

Nested types

class Form.TabIterator Iterates through the components on this form in traversal order.

Fields

protected boolean focusScrolling Indicates whether lists and containers should scroll only via focus and thus “jump” when moving to a larger component as was the case in older versions of Codename One.

Constructors

`public Form()`	Default constructor creates a simple form
`public Form(Layout contentPaneLayout)`	Constructor that accepts a layout
`public Form(String title)`	Sets the title after invoking the constructor
`public Form(String title, Layout contentPaneLayout)`	Sets the title after invoking the constructor

Methods

`public void setAllowEnableLayoutOnPaint(boolean allow)`	Enabling “layoutOnPaint” behaviour.
`public void addPasteListener(ActionListener l)`	Adds a listener to be notified when the user has initiated a paste event.
`public void removePasteListener(ActionListener l)`	Removes listener from being notified when the user has initiated a paste event.
`public void dispatchPaste(ActionEvent l)`	Fires a paste event to the paste listeners.
`public` `TextSelection getTextSelection()`	Gets TextSelection support for this form.
`public boolean isEnableCursors()`	Checks if custom cursors are enabled on this form.
`public void setEnableCursors(boolean e)`	Enable or disable custom cursors on this form.
`public` `Command getSourceCommand()`	Gets the source command that was used to navigate to this form.
`public void setSourceCommand(Command sourceCommand)`	Sets the source command that was used to navigate to this form.
`public` `VirtualInputDevice getCurrentInputDevice()`	Returns the current virtual input device in the form.
`public void setCurrentInputDevice(VirtualInputDevice device) throws Exception`	Sets the current virtual input device for the form.
`protected void initGlobalToolbar()`	Allows subclasses to disable the global toolbar for a specific form by overriding this method
`public void setOverrideInvisibleAreaUnderVKB(int invisibleAreaUnderVKB)`	Overrides the invisible area under the virtual keyboard with a given value.
`public int getInvisibleAreaUnderVKB()`	In some virtual keyboard implementations (notably iOS) this value is used to determine the height of the virtual keyboard
`public` `AnimationManager getAnimationManager()`	Returns the animation manager instance responsible for this form, this can be used to track/queue animations
`public boolean isFormBottomPaddingEditingMode()`	Toggles the way the virtual keyboard behaves, enabling this mode shrinks the screen but makes editing possible when working with text fields that aren’t in a scrollable container.
`public void setFormBottomPaddingEditingMode(boolean b)`	Toggles the way the virtual keyboard behaves, enabling this mode shrinks the screen but makes editing possible when working with text fields that aren’t in a scrollable container.
`public` `Rectangle getSafeArea()`	This method returns a rectangle defining the “safe” area of the display, which excludes areas on the screen that are covered by notches, task bars, rounded corners, etc.
`protected boolean shouldPaintStatusBar()`	This method returns the value of the theme constant `paintsTitleBarBool` and it is invoked internally in the code.
`protected` `Component createStatusBar()`	Subclasses can override this method to control the creation of the status bar component.
`public boolean isAlwaysTensile()`	Enable the tensile drag to work even when a component doesn’t have a scroll showable (scrollable flag still needs to be set to true)
`public void setAlwaysTensile(boolean alwaysTensile)`	Enable the tensile drag to work even when a component doesn’t have a scroll showable (scrollable flag still needs to be set to true)
`public boolean grabAnimationLock()`	Deprecated Allows grabbing a flag that is used by convention to indicate that you are running an exclusive animation.
`public void releaseAnimationLock()`	Deprecated Invoke this to release the animation lock that was grabbed in grabAnimationLock
`public` `Component findCurrentlyEditingComponent()`	Returns the component on this form that is currently being edited, or null if no component is currently being edited.
`public` `Container getTitleArea()`	Deprecated Title area manipulation might break with future changes to Codename One and might damage themeing/functionality of the Codename One application in some platforms
`public` `UIManager getUIManager()`	This method should be used by the Component to retrieve the correct UIManager to work with
`public void setUIManager(UIManager uiManager)`	Allows replacing the UIManager in a component hierarchy to update the look and feel only to a specific hierarchy
`public void addShowListener(ActionListener l)`	This listener would be invoked when show is completed
`public void removeShowListener(ActionListener l)`	Removes the show listener
`public void removeAllShowListeners()`	Removes all Show Listeners from this Form
`public void addOrientationListener(ActionListener l)`	This listener is invoked when device orientation changes on devices that support orientation change
`public void removeOrientationListener(ActionListener l)`	This listener is invoked when device orientation changes on devices that support orientation change
`public void addSizeChangedListener(ActionListener l)`	This listener is invoked when device size is changed
`public void removeSizeChangedListener(ActionListener l)`	Remove SizeChangedListener
`protected void hideNotify()`	This method is only invoked when the underlying canvas for the form is hidden this method isn’t called for form based events and is generally usable for suspend/resume based behavior
`protected void showNotify()`	This method is only invoked when the underlying canvas for the form is shown this method isn’t called for form based events and is generally usable for suspend/resume based behavior
`protected void sizeChanged(int w, int h)`	This method is only invoked when the underlying canvas for the form gets a size changed event.
`public void setSafeAreaChanged()`	Causes the display safe area to be recalculated the next time the form list laid out.
`public boolean isDragRegion(int x, int y)`	Deprecated Indicates if the section within the X/Y area is a “drag region” where we expect people to drag and never actually “press” in which case we can instantly start dragging making perceived performance faster.
`public int getDragRegionStatus(int x, int y)`	Indicates if the section within the X/Y area is a “drag region” where we expect people to drag or press in which case we can instantly start dragging making perceived performance faster.
`public` `Painter getGlassPane()`	Allows a developer that doesn’t derive from the form to draw on top of the form regardless of underlying changes or animations.
`public void setGlassPane(Painter glassPane)`	Allows a developer that doesn’t derive from the form to draw on top of the form regardless of underlying changes or animations.
`public` `Label getTitleComponent()`	Allows modifying the title attributes beyond style (e.g. setting icon/alignment etc.)
`public void setTitleComponent(Label title)`	Allows replacing the title with a different title component, thus allowing developers to create more elaborate title objects.
`public void setTitleComponent(Label title, Transition t)`	Allows replacing the title with a different title component, thus allowing developers to create more elaborate title objects.
`public void addKeyListener(int keyCode,` `ActionListener listener)`	Add a key listener to the given keycode for a callback when the key is released
`public void removeKeyListener(int keyCode,` `ActionListener listener)`	Removes a key listener from the given keycode
`public void removeGameKeyListener(int keyCode,` `ActionListener listener)`	Removes a game key listener from the given game keycode
`public void addGameKeyListener(int keyCode,` `ActionListener listener)`	Add a game key listener to the given gamekey for a callback when the key is released
`public final int getSoftButtonCount()`	Returns the number of buttons on the menu bar for use with getSoftButton()
`public` `Button getSoftButton(int offset)`	Returns the button representing the softbutton, this allows modifying softbutton attributes and behavior programmatically rather than by using the command API.
`public` `Style getMenuStyle()`	Returns the style of the menu
`public` `Style getTitleStyle()`	Returns the style of the title
`public void setTitleStyle(Style s)`	Deprecated Sets the style of the title programmatically
`protected void initLaf(UIManager uim)`	This method initializes the Component defaults constants
`public` `Command getDefaultCommand()`	Default command is invoked when a user presses fire, this functionality works well in some situations but might collide with elements such as navigation and combo boxes.
`public void setDefaultCommand(Command defaultCommand)`	Default command is invoked when a user presses fire, this functionality works well in some situations but might collide with elements such as navigation and combo boxes.
`public` `Command getClearCommand()`	Indicates the command that is defined as the clear command in this form.
`public void setClearCommand(Command clearCommand)`	Indicates the command that is defined as the clear command in this form.
`public` `Command setBackCommand(String name, Image icon, ActionListener ev)`	Shorthand for `#setBackCommand(com.codename1.ui.Command)` that dynamically creates the command using `com.codename1.ui.Image, com.codename1.ui.events.ActionListener)`.
`public` `Command getBackCommand()`	Indicates the command that is defined as the back command out of this form.
`public void setBackCommand(Command backCommand)`	Indicates the command that is defined as the back command out of this form.
`public void setPopGuard(PopGuard guard)`	Installs an optional guard that is consulted before back/pop navigation leaves this form.
`public` `PopGuard getPopGuard()`	Returns the currently installed pop guard, or null.
`public boolean checkPopGuard(PopReason reason)`	Consults the installed pop guard for the given reason.
`public` `Container getContentPane()`	This method returns the Content pane instance
`public` `Container asContainer()`
`public` `Container getLayeredPane()`	This method returns the layered pane of the Form, the layered pane is laid on top of the content pane and is created lazily upon calling this method the layer will be created.
`public` `Container getLayeredPane(Class c, boolean top)`	Returns the layered pane for the class and if one doesn’t exist a new one is created dynamically and returned
`public` `Container getLayeredPane(Class c, int zIndex)`	Returns the layered pane for the class and if one doesn’t exist a new one is created dynamically and returned
`public` `Container getFormLayeredPane(Class c, boolean top)`	Returns the layered pane for the class and if one doesn’t exist a new one is created dynamically and returned.
`protected` `Container getLayeredPaneIfExists()`	Gets the layered pane of the container without trying to create it.
`protected` `Container getFormLayeredPaneIfExists()`	Gets the form layered pane of the container without trying to create it.
`public void removeAll()`	Removes all Components from the Content Pane
`public void setBgImage(Image bgImage)`	Deprecated Sets the background image to show behind the form
`public void stopEditing(Runnable onFinish)`	Stops any active editing on the form.
`public boolean isEditing()`	Checks if the component is currently being edited.
`public` `String getTitle()`	Returns the Form title text
`public void setTitle(String title)`	Sets the Form title to the given text
`public void addComponent(Component cmp)`	Adds Component to the Form’s Content Pane
`public void addComponent(Object constraints, Component cmp)`	Adds a Component to the Container
`public void addComponent(int index,` `Object constraints, Component cmp)`	Adds a Component to the Container
`public void addComponent(int index,` `Component cmp)`	Adds Component to the Form’s Content Pane
`public void replace(Component current, Component next, Transition t)`	This method replaces the current Component with the next Component.
`public void replaceAndWait(Component current, Component next, Transition t)`	This method replaces the current Component with the next Component.
`public void removeComponent(Component cmp)`	Removes a component from the Form’s Content Pane
`public void animateHierarchy(int duration)`	Animates a pending hierarchy of components into place, this effectively replaces revalidate with a more visual form of animation
`public void animateHierarchyAndWait(int duration)`	Animates a pending hierarchy of components into place, this effectively replaces revalidate with a more visual form of animation.
`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
`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.
`public void animateLayout(int duration)`	Animates a pending layout into place, this effectively replaces revalidate with a more visual form of animation
`public void animateLayoutAndWait(int duration)`	Animates a pending layout into place, this effectively replaces revalidate with a more visual form of animation.
`public void animateLayoutFade(int duration, int startingOpacity)`	Animates a pending layout into place, this effectively replaces revalidate with a more visual form of animation
`public void animateLayoutFadeAndWait(int duration, int startingOpacity)`	Animates a pending layout into place, this effectively replaces revalidate with a more visual form of animation.
`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.
`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.
`public boolean isTopLevelShowing()`	Whether this top level is the one currently on screen.
`public final boolean hasMedia()`	Used by the implementation to prevent flickering when flushing the double buffer
`public final void registerAnimated(Animation cmp)`	The given component is interested in animating its appearance and will start receiving callbacks when it is visible in the form allowing it to animate its appearance.
`protected void onRegisterAnimated(Animation cmp)`	Callback that’s invoked by registerAnimated to let subclasses keep track of animation registration.
`public void deregisterAnimated(Animation cmp)`	Indicate that cmp would no longer like to receive animation events
`public boolean animate()`	Allows the animation to reduce “repaint” calls when it returns false.
`public int getSideGap()`	The form itself should
`protected void paintScrollbars(Graphics g)`	Paints the UI for the scrollbars on the component, this will be invoked only for scrollable components.
`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!
`public void paintBackground(Graphics g)`	Exposing the background painting for the benefit of animations
`public` `Transition getTransitionInAnimator()`	This property allows us to define a an animation that will draw the transition for entering this form.
`public void setTransitionInAnimator(Transition transitionInAnimator)`	This property allows us to define a an animation that will draw the transition for entering this form.
`public` `Transition getTransitionOutAnimator()`	This property allows us to define a an animation that will draw the transition for exiting this form.
`public void setTransitionOutAnimator(Transition transitionOutAnimator)`	This property allows us to define a an animation that will draw the transition for exiting this form.
`public void addCommandListener(ActionListener l)`	A listener that is invoked when a command is clicked allowing multiple commands to be handled by a single block
`public void removeCommandListener(ActionListener l)`	A listener that is invoked when a command is clicked allowing multiple commands to be handled by a single block
`protected void actionCommand(Command cmd)`	Invoked to allow subclasses of form to handle a command from one point rather than implementing many command instances.
`public void dispatchCommand(Command cmd, ActionEvent ev)`	Dispatches a command via the standard form mechanism of firing a command event
`public void show()`	Displays the current form on the screen
`public void showBack()`	Displays the current form on the screen, this version of the method is useful for “back” navigation since it reverses the direction of the transition.
`public void addPointerPressedListener(ActionListener l)`	Adds a listener to the pointer event
`public void removePointerPressedListener(ActionListener l)`	Removes the listener from the pointer event
`public void addPointerDraggedListener(ActionListener l)`	Adds a listener to the pointer event
`public void removePointerDraggedListener(ActionListener l)`	Removes the listener from the pointer event
`public void addPointerReleasedListener(ActionListener l)`	Adds a listener to the pointer event
`public void removePointerReleasedListener(ActionListener l)`	Removes the listener from the pointer event
`public void addLongPressListener(ActionListener l)`	Adds a listener to the pointer event
`public void removeLongPressListener(ActionListener l)`	Removes the listener from the pointer event
`public boolean isSmoothScrolling()`	Indicates that scrolling through the component should work as an animation
`public void setSmoothScrolling(boolean smoothScrolling)`	Indicates that scrolling through the component should work as an animation
`public int getScrollAnimationSpeed()`	Scroll animation speed in milliseconds allowing a developer to slow down or accelerate the smooth animation mode
`public void setScrollAnimationSpeed(int animationSpeed)`	Scroll animation speed in milliseconds allowing a developer to slow down or accelerate the smooth animation mode
`protected void onShow()`	Allows subclasses to bind functionality that occurs when a specific form or dialog appears on the screen
`protected void onShowCompleted()`	Allows subclasses to bind functionality that occurs when a specific form or dialog is “really” showing hence when the transition is totally complete (unlike onShow which is called on intent).
`public final` `Form getComponentForm()`	Returns the Component Form or null if this Component is not added yet to a form
`public` `TopLevelContainer getTopLevelContainer()`	Returns the top level container this component currently belongs to, which is either the `Form` filling the main surface or the `Window` of a native desktop window, or null when this component is not attached to one.
`public` `Component getFocused()`	Returns the current focus component for this form
`public void setFocused(Component focused)`	Sets the focused component and fires the appropriate events to make it so
`protected void longKeyPress(int keyCode)`	If this Component is focused this method is invoked when the user presses and holds the key
`public void longPointerPress(int x, int y)`	If this Component is focused this method is invoked when the user presses and holds the pointer on the Component
`protected boolean shouldSendPointerReleaseToOtherForm()`	Indicates whether this form wants to receive pointerReleased events for touch events that started in a different form
`public` `Component getNextComponent(Component current)`	Gets the next component in focus traversal order.
`public` `Component getPreviousComponent(Component current)`	Gets the previous component in focus traversal order.
`public` `Form.TabIterator getTabIterator(Component start)`	Returns an iterator that iterates over all of the components in this form, ordered by their tab index.
`public void keyPressed(int keyCode)`	If this Component is focused, the key pressed event will call this method
`public` `Layout getLayout()`	Returns the layout manager of the form’s content pane.
`public void setLayout(Layout layout)`	Sets the layout manager responsible for arranging this container
`public boolean isMinimizeOnBack()`	When set to true the physical back button will minimize the application
`public void setMinimizeOnBack(boolean minimizeOnBack)`	When set to true the physical back button will minimize the application
`public void keyReleased(int keyCode)`	If this Component is focused, the key released event will call this method
`public void keyRepeated(int keyCode)`	If this Component is focused, the key repeat event will call this method.
`protected boolean resumeDragAfterScrolling(int x, int y)`	This method fixes this tensile drag issue.
`public void pointerPressed(int x, int y)`	If this Component is focused, the pointer pressed event will call this method
`public <C extends Component> void addComponentAwaitingRelease(C c)`	Returns this top level as a `Container`.
`public <C extends Component> void removeComponentAwaitingRelease(C c)`	Stops tracking a component that was waiting for a pointer release.
`public 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 void pointerDragged(int x, int y)`	If this Component is focused, the pointer dragged event will call this method
`public void pointerDragged(int[] x, int[] y)`	If this Component is focused, the pointer dragged event will call this method
`public void pointerHoverReleased(int[] x, int[] y)`	Invoked for devices where the pointer can hover without actually clicking the display.
`public void pointerHoverPressed(int[] x, int[] y)`	Invoked for devices where the pointer can hover without actually clicking the display.
`public void pointerHover(int[] x, int[] y)`	Invoked for devices where the pointer can hover without actually clicking the display.
`public boolean isSingleFocusMode()`	Returns true if there is only one focusable member in this form.
`public void pointerReleased(int x, int y)`	If this Component is focused, the pointer released event will call this method
`public boolean isScrollVisible()`	Indicate whether this component scroll is visible
`public void setScrollVisible(boolean isScrollVisible)`	Set whether this component scroll is visible
`public int getComponentIndex(Component cmp)`	Returns the Component index in the Container
`public void addCommand(Command cmd, int offset)`	Deprecated Adds a command to the menu bar softkeys or into the menu dialog, this version of add allows us to place a command in an arbitrary location.
`public int getCommandCount()`	Deprecated A helper method to check the amount of commands within the form menu
`public` `Command getCommand(int index)`	Returns the command occupying the given index
`public final void addCommand(Command cmd)`	Deprecated Adds a command to the menu bar softkeys.
`public void removeCommand(Command cmd)`	Removes the command from the menu bar softkeys
`public` `Component findNextFocusVertical(boolean down)`	This method returns the next focusable Component vertically
`public` `Component findNextFocusHorizontal(boolean right)`	This method returns the next focusable Component horizontally
`public boolean isCyclicFocus()`	Indicates whether focus should cycle within the form
`public void setCyclicFocus(boolean cyclicFocus)`	Indicates whether focus should cycle within the form
`public void scrollComponentToVisible(Component c)`	Makes sure the component is visible in the scroll if this container is scrollable
`public void setMenuCellRenderer(ListCellRenderer menuCellRenderer)`	Determine the cell renderer used to render menu elements for themeing the look of the menu options
`public void removeAllCommands()`	Clear menu commands from the menu bar
`public void setRTL(boolean r)`	Is the component a bidi RTL component
`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.
`public boolean isScrollable()`	Indicates whether the component should/could scroll by default a component is not scrollable.
`public void setScrollable(boolean scrollable)`	The equivalent of calling both setScrollableY and setScrollableX
`public boolean isScrollableX()`	Indicates whether the component should/could scroll on the X axis
`public void setScrollableX(boolean scrollableX)`	Sets whether the component should/could scroll on the X axis
`public boolean isScrollableY()`	Indicates whether the component should/could scroll on the Y axis
`public void setScrollableY(boolean scrollableY)`	Sets whether the component should/could scroll on the Y axis
`public void setVisible(boolean visible)`	Toggles visibility of the component
`public int getTintColor()`	Default color for the screen tint when a dialog or a menu is shown
`public void setTintColor(int tintColor)`	Default color for the screen tint when a dialog or a menu is shown
`public void setMenuTransitions(Transition transitionIn, Transition transitionOut)`	Sets the menu transitions for showing/hiding the menu, can be null…
`protected` `String paramString()`	Returns a string representing the state of this component.
`public` `MenuBar getMenuBar()`	Returns the associated Menu Bar object
`public void setMenuBar(MenuBar menuBar)`	Sets the associated MenuBar Object.
`public void setToolBar(Toolbar toolbar)`	Deprecated Sets the Form Toolbar
`public` `Toolbar getToolbar()`	Gets the Form Toolbar if exists or null
`public void setToolbar(Toolbar toolbar)`	Sets the Form Toolbar
`public boolean isFocusScrolling()`	Indicates whether lists and containers should scroll only via focus and thus “jump” when moving to a larger component as was the case in older versions of Codename One.
`public void setFocusScrolling(boolean focusScrolling)`	Indicates whether lists and containers should scroll only via focus and thus “jump” when moving to a larger component as was the case in older versions of Codename One.
`public` `String[] getPropertyNames()`	A component may expose mutable property names for a UI designer to manipulate, this API is designed for usage internally by the GUI builder code
`public` `Class[] getPropertyTypes()`	Matches the property names method (see that method for further details).
`public` `String[] getPropertyTypeNames()`	This method is here to workaround an XMLVM array type bug where property types aren’t identified properly, it returns the names of the types using the following type names: String,int,double,long,byte,short,char,String[],String[][],byte[],I…
`public` `Object getPropertyValue(String name)`	Returns the current value of the property name, this method is used by the GUI builder
`public` `String setPropertyValue(String name, Object value)`	Sets a new value to the given property, returns an error message if failed and null if successful.
`public` `TextArea getEditOnShow()`	A text component that will receive focus and start editing immediately as the form is shown
`public void setEditOnShow(TextArea editOnShow)`	A text component that will receive focus and start editing immediately as the form is shown

Inherited fields

Inherited methods

Field details

focusScrolling

protected boolean focusScrolling

Indicates whether lists and containers should scroll only via focus and thus “jump” when moving to a larger component as was the case in older versions of Codename One.

Constructor details

Form

public Form()

Default constructor creates a simple form

Form

public Form(Layout contentPaneLayout)

Constructor that accepts a layout

Parameters

contentPaneLayout Layout: the layout for the content pane

Form

public Form(String title)

Sets the title after invoking the constructor

Parameters

title String: the form title

Form

public Form(String title, Layout contentPaneLayout)

Sets the title after invoking the constructor

Parameters

title String: the form title
contentPaneLayout Layout: the layout for the content pane

Method details

setAllowEnableLayoutOnPaint

public void setAllowEnableLayoutOnPaint(boolean allow)

Enabling “layoutOnPaint” behaviour. Setting this flag to true will cause this form and all of its containers to lay themselves out whenever they are painted. This carries a performance penalty.

Historical Note: “layoutOnPaint” behaviour has been “on” since the original commit to Google code in 2012, but it isn’t clear, now, why it was necessary. It was likely to fix an edge case in certain layouts that is no longer relevant. As of 7.0, we are disabling this behaviour by default because it carries such performance penalties, but allowing developers to opt-in to it using this method.

Parameters

allow boolean: Whether to allow layoutOnPaint behaviour in this this form and it’s containers.

addPasteListener

public void addPasteListener(ActionListener l)

Adds a listener to be notified when the user has initiated a paste event. This will primarily occur only on desktop devices which allow the user to initiate a paste outside the UI of the app itself, either using a key code (Command/Ctrl V), or a menu (Edit > Paste).

The event will be fired after the paste action has updated the clipboard contents, so you can access the clipboard contents via Display#getPasteDataFromClipboard().

Parameters

l ActionListener: Listener registered to receive paste events.

removePasteListener

public void removePasteListener(ActionListener l)

Removes listener from being notified when the user has initiated a paste event.

Parameters

l ActionListener: Listener to unregister to receive paste events.

dispatchPaste

public void dispatchPaste(ActionEvent l)

Fires a paste event to the paste listeners. For internal use.

Parameters

l ActionEvent: The paste event. Includes no useful data currently.

getTextSelection

public TextSelection getTextSelection()

Gets TextSelection support for this form.

Returns

The text selection support for this form.

isEnableCursors

public boolean isEnableCursors()

Checks if custom cursors are enabled on this form. They are turned off by default since they incur some overhead.

Returns

True if cursors are enabled on this form.

setEnableCursors

public void setEnableCursors(boolean e)

Enable or disable custom cursors on this form. They are turned off by default since they incur some overhead.

Parameters

e boolean: True to enable cursors. False to disable them.

getSourceCommand

public Command getSourceCommand()

Gets the source command that was used to navigate to this form. This can be used to pass context information to the form.

Returns

The source command.

setSourceCommand

public void setSourceCommand(Command sourceCommand)

Sets the source command that was used to navigate to this form. This can be used to pass context information to the form.

Parameters

sourceCommand Command: The source command.

getCurrentInputDevice

public VirtualInputDevice getCurrentInputDevice()

Returns the current virtual input device in the form.

Returns

The current input device in the form.

setCurrentInputDevice

public void setCurrentInputDevice(VirtualInputDevice device)
throws Exception

Sets the current virtual input device for the form. This will execute the VirtualInputDevice#close() method of the current input device, and then set device as the new current input device.

Some examples of virtual input devices are the Picker widget and the virtual keyboard.

Throws

Exception

initGlobalToolbar

protected void initGlobalToolbar()

Allows subclasses to disable the global toolbar for a specific form by overriding this method

setOverrideInvisibleAreaUnderVKB

public void setOverrideInvisibleAreaUnderVKB(int invisibleAreaUnderVKB)

Overrides the invisible area under the virtual keyboard with a given value. This is used by lightweight components to simulate the virtual keyboard, so that they will respect #setFormBottomPaddingEditingMode(boolean).

Warning: This setting is generally for internal use only, and should only be used if you know what you are doing. After setting this value to a non-negative value, it will override the “real” area under the VKB if the read VKB is shown.

To reset this after the lightweight component is hidden, set the value to -1.

Parameters

invisibleAreaUnderVKB int: The area hidden by the VKB in pixels.

getInvisibleAreaUnderVKB

public int getInvisibleAreaUnderVKB()

In some virtual keyboard implementations (notably iOS) this value is used to determine the height of the virtual keyboard

Returns

height in pixels of the virtual keyboard

getAnimationManager

public AnimationManager getAnimationManager()

Returns the animation manager instance responsible for this form, this can be used to track/queue animations

Returns

the animation manager

isFormBottomPaddingEditingMode

public boolean isFormBottomPaddingEditingMode()

Toggles the way the virtual keyboard behaves, enabling this mode shrinks the screen but makes editing possible when working with text fields that aren’t in a scrollable container.

Returns

true when this mode is enabled

setFormBottomPaddingEditingMode

public void setFormBottomPaddingEditingMode(boolean b)

Toggles the way the virtual keyboard behaves, enabling this mode shrinks the screen but makes editing possible when working with text fields that aren’t in a scrollable container.

Parameters

b boolean: true to enable false to disable

getSafeArea

public Rectangle getSafeArea()

This method returns a rectangle defining the “safe” area of the display, which excludes areas on the screen that are covered by notches, task bars, rounded corners, etc.

This feature was primarily added to deal with the task bar on the iPhone X, which is displayed on the screen near the bottom edge, and can interfere with components that are laid out at the bottom of the screen.

Most platforms will simply return a Rectangle with bounds (0, 0, displayWidth, displayHeight). iPhone X will return a rectangle that excludes the notch, and task bar regions.

Returns

The safe area on which to draw.

shouldPaintStatusBar

protected boolean shouldPaintStatusBar()

This method returns the value of the theme constant paintsTitleBarBool and it is invoked internally in the code. You can override this method to toggle the appearance of the status bar on a per-form basis

Returns

the value of the paintsTitleBarBool theme constant

createStatusBar

protected Component createStatusBar()

Subclasses can override this method to control the creation of the status bar component. Notice that this method will only be invoked if the paintsTitleBarBool theme constant is true which it is on iOS by default

Returns

a Component that represents the status bar if the OS requires status bar spacing

isAlwaysTensile

public boolean isAlwaysTensile()

Enable the tensile drag to work even when a component doesn’t have a scroll showable (scrollable flag still needs to be set to true)

Returns

the alwaysTensile

setAlwaysTensile

public void setAlwaysTensile(boolean alwaysTensile)

Enable the tensile drag to work even when a component doesn’t have a scroll showable (scrollable flag still needs to be set to true)

Parameters

alwaysTensile boolean: the alwaysTensile to set

grabAnimationLock

public boolean grabAnimationLock()

Deprecated. this is effectively invalidated by the newer animation framework

Allows grabbing a flag that is used by convention to indicate that you are running an exclusive animation. This is used by some code to prevent collision between optional animation

Returns

whether the lock was acquired or not

releaseAnimationLock

public void releaseAnimationLock()

Deprecated. this is effectively invalidated by the newer animation framework

Invoke this to release the animation lock that was grabbed in grabAnimationLock

findCurrentlyEditingComponent

public Component findCurrentlyEditingComponent()

Returns the component on this form that is currently being edited, or null if no component is currently being edited.

Returns

The currently edited component on this form.

getTitleArea

public Container getTitleArea()

Deprecated. this method was exposed to allow some hacks, you are advised not to use it. There are some alternatives such as command behavior (thru Display or the theme constants)

Title area manipulation might break with future changes to Codename One and might damage themeing/functionality of the Codename One application in some platforms

Returns

the container containing the title

getUIManager

public UIManager getUIManager()

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

Returns

a UIManager instance

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: UIManager instance

addShowListener

public void addShowListener(ActionListener l)

This listener would be invoked when show is completed

Parameters

l ActionListener: listener

removeShowListener

public void removeShowListener(ActionListener l)

Removes the show listener

Parameters

l ActionListener: the listener

removeAllShowListeners

public void removeAllShowListeners()

Removes all Show Listeners from this Form

addOrientationListener

public void addOrientationListener(ActionListener l)

This listener is invoked when device orientation changes on devices that support orientation change

Parameters

l ActionListener: listener

removeOrientationListener

public void removeOrientationListener(ActionListener l)

This listener is invoked when device orientation changes on devices that support orientation change

Parameters

l ActionListener: the listener

addSizeChangedListener

public void addSizeChangedListener(ActionListener l)

This listener is invoked when device size is changed

Parameters

l ActionListener: listener

removeSizeChangedListener

public void removeSizeChangedListener(ActionListener l)

Remove SizeChangedListener

Parameters

l ActionListener: the listener

hideNotify

protected void hideNotify()

This method is only invoked when the underlying canvas for the form is hidden this method isn’t called for form based events and is generally usable for suspend/resume based behavior

showNotify

protected void showNotify()

This method is only invoked when the underlying canvas for the form is shown this method isn’t called for form based events and is generally usable for suspend/resume based behavior

sizeChanged

protected void sizeChanged(int w, int h)

This method is only invoked when the underlying canvas for the form gets a size changed event. This method will trigger a relayout of the Form. This method will get the callback only if this Form is the Current Form

Parameters

w int: the new width of the Form
h int: the new height of the Form

setSafeAreaChanged

public void setSafeAreaChanged()

Causes the display safe area to be recalculated the next time the form list laid out.

isDragRegion

public boolean isDragRegion(int x, int y)

Deprecated. this method was replaced by getDragRegionStatus

Indicates if the section within the X/Y area is a “drag region” where we expect people to drag and never actually “press” in which case we can instantly start dragging making perceived performance faster. This is invoked by the implementation code to optimize drag start behavior

Parameters

x int: x location for the touch
y int: y location for the touch

Returns

true if the touch is in a region specifically designated as a “drag region”

getDragRegionStatus

public int getDragRegionStatus(int x, int y)

Indicates if the section within the X/Y area is a “drag region” where we expect people to drag or press in which case we can instantly start dragging making perceived performance faster. This is invoked by the implementation code to optimize drag start behavior

Parameters

x int: x location for the touch
y int: y location for the touch

Returns

one of the DRAG_REGION_* values

getGlassPane

public Painter getGlassPane()

Allows a developer that doesn’t derive from the form to draw on top of the form regardless of underlying changes or animations. This is useful for watermarks or special effects (such as tinting) it is also useful for generic drawing of validation errors etc… A glass pane is generally transparent or translucent and allows the the UI below to be seen.

The example shows a glasspane running on top of a field to show a validation hint, notice that for real world usage you should probably look into com.codename1.ui.validation.Validator

Form hi = new Form("Glass Pane", new BoxLayout(BoxLayout.Y_AXIS));
Style s = UIManager.getInstance().getComponentStyle("Label");
s.setFgColor(0xff0000);
s.setBgTransparency(0);
Image warningImage = FontImage.createMaterial(FontImage.MATERIAL_WARNING, s).toImage();
TextField tf1 = new TextField("My Field");
tf1.getAllStyles().setMarginUnit(Style.UNIT_TYPE_DIPS);
tf1.getAllStyles().setMargin(5, 5, 5, 5);
hi.add(tf1);
hi.setGlassPane((g, rect) -> {
    int x = tf1.getAbsoluteX() + tf1.getWidth();
    int y = tf1.getAbsoluteY();
    x -= warningImage.getWidth() / 2;
    y += (tf1.getHeight() / 2 - warningImage.getHeight() / 2);
    g.drawImage(warningImage, x, y);
});
hi.show();

Returns

the instance of the glass pane for this form

setGlassPane

public void setGlassPane(Painter glassPane)

The example shows a glasspane running on top of a field to show a validation hint, notice that for real world usage you should probably look into com.codename1.ui.validation.Validator

Form hi = new Form("Glass Pane", new BoxLayout(BoxLayout.Y_AXIS));
Style s = UIManager.getInstance().getComponentStyle("Label");
s.setFgColor(0xff0000);
s.setBgTransparency(0);
Image warningImage = FontImage.createMaterial(FontImage.MATERIAL_WARNING, s).toImage();
TextField tf1 = new TextField("My Field");
tf1.getAllStyles().setMarginUnit(Style.UNIT_TYPE_DIPS);
tf1.getAllStyles().setMargin(5, 5, 5, 5);
hi.add(tf1);
hi.setGlassPane((g, rect) -> {
    int x = tf1.getAbsoluteX() + tf1.getWidth();
    int y = tf1.getAbsoluteY();
    x -= warningImage.getWidth() / 2;
    y += (tf1.getHeight() / 2 - warningImage.getHeight() / 2);
    g.drawImage(warningImage, x, y);
});
hi.show();

Parameters

glassPane Painter: a new glass pane to install. It is generally recommended to use a painter chain if more than one painter is required.

getTitleComponent

public Label getTitleComponent()

Allows modifying the title attributes beyond style (e.g. setting icon/alignment etc.)

Returns

the component representing the title for the form

setTitleComponent

public void setTitleComponent(Label title)

Allows replacing the title with a different title component, thus allowing developers to create more elaborate title objects.

Parameters

title Label: new title component

setTitleComponent

public void setTitleComponent(Label title, Transition t)

Allows replacing the title with a different title component, thus allowing developers to create more elaborate title objects. This version of the method allows special effects for title replacement such as transitions for title entering

Parameters

title Label: new title component
t Transition: transition for title replacement

addKeyListener

public void addKeyListener(int keyCode, ActionListener listener)

Add a key listener to the given keycode for a callback when the key is released

Parameters

keyCode int: code on which to send the event
listener ActionListener: listener to invoke when the key code released.

removeKeyListener

public void removeKeyListener(int keyCode, ActionListener listener)

Removes a key listener from the given keycode

Parameters

keyCode int: code on which the event is sent
listener ActionListener: listener instance to remove

removeGameKeyListener

public void removeGameKeyListener(int keyCode, ActionListener listener)

Removes a game key listener from the given game keycode

Parameters

keyCode int: code on which the event is sent
listener ActionListener: listener instance to remove

addGameKeyListener

public void addGameKeyListener(int keyCode, ActionListener listener)

Add a game key listener to the given gamekey for a callback when the key is released

Parameters

keyCode int: code on which to send the event
listener ActionListener: listener to invoke when the key code released.

getSoftButtonCount

public final int getSoftButtonCount()

Returns the number of buttons on the menu bar for use with getSoftButton()

Returns

the number of softbuttons

getSoftButton

public Button getSoftButton(int offset)

Returns the button representing the softbutton, this allows modifying softbutton attributes and behavior programmatically rather than by using the command API. Notice that this API behavior is fragile since the button mapped to a particular offset might change based on the command API

Parameters

offset int: the offest of the softbutton

Returns

a button that can be manipulated

getMenuStyle

public Style getMenuStyle()

Returns the style of the menu

Returns

the style of the menu

getTitleStyle

public Style getTitleStyle()

Returns the style of the title

Returns

the style of the title

setTitleStyle

public void setTitleStyle(Style s)

Deprecated. this method doesn’t take into consideration multiple styles

Sets the style of the title programmatically

Parameters

s Style: new style

initLaf

protected void initLaf(UIManager uim)

This method initializes the Component defaults constants

getDefaultCommand

public Command getDefaultCommand()

Default command is invoked when a user presses fire, this functionality works well in some situations but might collide with elements such as navigation and combo boxes. Use with caution.

Returns

the command to treat as default

setDefaultCommand

public void setDefaultCommand(Command defaultCommand)

Default command is invoked when a user presses fire, this functionality works well in some situations but might collide with elements such as navigation and combo boxes. Use with caution.

Parameters

defaultCommand Command: the command to treat as default

getClearCommand

public Command getClearCommand()

Indicates the command that is defined as the clear command in this form. A clear command can be used both to map to a “clear” hardware button if such a button exists.

Returns

the command to treat as the clear Command

setClearCommand

public void setClearCommand(Command clearCommand)

Indicates the command that is defined as the clear command in this form. A clear command can be used both to map to a “clear” hardware button if such a button exists.

Parameters

clearCommand Command: the command to treat as the clear Command

setBackCommand

public Command setBackCommand(String name, Image icon, ActionListener ev)

Shorthand for #setBackCommand(com.codename1.ui.Command) that dynamically creates the command using com.codename1.ui.Image, com.codename1.ui.events.ActionListener).

Parameters

name String: the name/title of the command
icon Image: the icon for the command
ev ActionListener: the even handler

Returns

a newly created Command instance

getBackCommand

public Command getBackCommand()

Indicates the command that is defined as the back command out of this form. A back command can be used both to map to a hardware button (e.g. on the Sony Ericsson devices) and by elements such as transitions etc. to change the behavior based on direction (e.g. slide to the left to enter screen and slide to the right to exit with back).

Returns

the command to treat as the back Command

setBackCommand

public void setBackCommand(Command backCommand)

Parameters

backCommand Command: the command to treat as the back Command

setPopGuard

public void setPopGuard(PopGuard guard)

Installs an optional guard that is consulted before back/pop navigation leaves this form.

The guard fires for:

The back command (toolbar / menu back button).
Hardware back (Android back button, iOS edge-swipe back).
Programmatic com.codename1.router.Router#pop and replace calls.

If the guard returns false the navigation is suppressed; the guard itself is responsible for any follow-up UI (e.g. showing a confirm dialog and then calling Router.pop() once the user accepts).

Pass null to remove a previously installed guard.

Since 7.0

getPopGuard

public PopGuard getPopGuard()

Returns the currently installed pop guard, or null.

Since 7.0

checkPopGuard

public boolean checkPopGuard(PopReason reason)

Consults the installed pop guard for the given reason. Returns true when no guard is installed or the guard permits the pop. Called by Router, by the back-command dispatcher, by platform back-key glue, and may be called by developer code that implements its own back navigation and wants to honor any pop guard installed on the form.

Since 7.0

getContentPane

public Container getContentPane()

This method returns the Content pane instance

Returns

a content pane instance

asContainer

public Container asContainer()

getLayeredPane

public Container getLayeredPane()

This method returns the layered pane of the Form, the layered pane is laid on top of the content pane and is created lazily upon calling this method the layer will be created. This is equivalent to getLayeredPane(null, false).

Returns

the LayeredPane

getLayeredPane

public Container getLayeredPane(Class c, boolean top)

Returns the layered pane for the class and if one doesn’t exist a new one is created dynamically and returned

Parameters

c Class: the class with which this layered pane is associated, null for the global layered pane which is always on the bottom
top boolean: if created this indicates whether the layered pane should be added on top or bottom

Returns

the layered pane instance

getLayeredPane

public Container getLayeredPane(Class c, int zIndex)

Returns the layered pane for the class and if one doesn’t exist a new one is created dynamically and returned

Parameters

c Class: the class with which this layered pane is associated, null for the global layered pane which is always on the bottom
zIndex int: if created this indicates the zIndex at which the pane is placed. Higher z values in front of lower z values.

Returns

the layered pane instance

getFormLayeredPane

public Container getFormLayeredPane(Class c, boolean top)

Returns the layered pane for the class and if one doesn’t exist a new one is created dynamically and returned. This version of the method returns a layered pane on the whole form

Parameters

c Class: the class with which this layered pane is associated, null for the global layered pane which is always on the bottom
top boolean: if created this indicates whether the layered pane should be added on top or bottom

Returns

the layered pane instance

getLayeredPaneIfExists

protected Container getLayeredPaneIfExists()

Gets the layered pane of the container without trying to create it. If #getLayeredPane() hasn’t been called yet for the form, then the layered pane will be null.

Returns

The layered pane if it’s been created - or null.

getFormLayeredPaneIfExists

protected Container getFormLayeredPaneIfExists()

Gets the form layered pane of the container without trying to create it. If boolean) hasn’t been called yet for the form, then the layered pane will be null.

Returns

The layered pane if it’s been created - or null.

removeAll

public void removeAll()

Removes all Components from the Content Pane

setBgImage

public void setBgImage(Image bgImage)

Deprecated. Use the style directly

Sets the background image to show behind the form

Parameters

bgImage Image: the background image

stopEditing

public void stopEditing(Runnable onFinish)

Stops any active editing on the form. Closes keyboard if it is opened.

Parameters

onFinish Runnable: Callback to run on finish.

isEditing

public boolean isEditing()

Checks if the component is currently being edited.

Returns

True if the component is currently being edited.

getTitle

public String getTitle()

Returns the Form title text

Returns

returns the form title

setTitle

public void setTitle(String title)

Sets the Form title to the given text

Parameters

title String: the form title

addComponent

public void addComponent(Component cmp)

Adds Component to the Form’s Content Pane

Parameters

cmp Component: the added param

addComponent

public void addComponent(Object constraints, Component cmp)

Adds a Component to the Container

Parameters

constraints Object: 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: component to add

addComponent

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

Adds a Component to the Container

Parameters

index int: location to insert the Component
constraints Object: 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: component to add

addComponent

public void addComponent(int index, Component cmp)

Adds Component to the Form’s Content Pane

Parameters

index int: location to insert the Component
cmp Component: the added param

Throws

ArrayIndexOutOfBoundsException: if index is out of bounds
IllegalArgumentException: if Component is already contained or the cmp is a Form Component

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 Component: a Component to remove from the Container
next Component: a Component that replaces the current Component
t Transition: 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)

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 Component: a Component to remove from the Container
next Component: a Component that replaces the current Component
t Transition: a Transition between the add and removal of the Components a Transition can be null

removeComponent

public void removeComponent(Component cmp)

Removes a component from the Form’s Content Pane

Parameters

cmp Component: the component to be removed

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 int: the duration in milliseconds for the animation

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 int: the duration in milliseconds for the animation

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 int: the duration in milliseconds for the animation
startingOpacity int: the initial opacity to give to the animated components

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 int: the duration in milliseconds for the animation
startingOpacity int: the initial opacity to give to the animated components

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 int: the duration in milliseconds for the animation

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 int: the duration in milliseconds for the animation

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 int: the duration in milliseconds for the animation
startingOpacity int: 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 int: the duration in milliseconds for the animation
startingOpacity int: the initial opacity to give to the animated components

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 int: the duration of the animation
opacity int: the opacity to which the layout will reach, allows fading out the components
callback Runnable: 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 int: the duration of the animation
opacity int: the opacity to which the layout will reach, allows fading out the components

isTopLevelShowing

public boolean isTopLevelShowing()

Whether this top level is the one currently on screen. Inert unless this container is a top level.

Returns

true when this top level is showing

hasMedia

public final boolean hasMedia()

Used by the implementation to prevent flickering when flushing the double buffer

Returns

true if the form has media components within it

registerAnimated

public final void registerAnimated(Animation cmp)

The given component is interested in animating its appearance and will start receiving callbacks when it is visible in the form allowing it to animate its appearance. This method would not register a component instance more than once

Parameters

cmp Animation: component that would be animated

onRegisterAnimated

protected void onRegisterAnimated(Animation cmp)

Callback that’s invoked by registerAnimated to let subclasses keep track of animation registration.

Parameters

cmp Animation: component that would be animated

deregisterAnimated

public void deregisterAnimated(Animation cmp)

Indicate that cmp would no longer like to receive animation events

Parameters

cmp Animation: component that would no longer receive animation events

animate

public boolean animate()

Allows the animation to reduce “repaint” calls when it returns false. It is called once for every frame. Frames are defined by the com.codename1.ui.Display class.

Returns

true if a repaint is desired or false if no repaint is necessary

getSideGap

public int getSideGap()

The form itself should

Returns

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

paintScrollbars

protected void paintScrollbars(Graphics g)

Paints the UI for the scrollbars on the component, this will be invoked only for scrollable components. This method invokes the appropriate X/Y versions to do all the work.

Parameters

g Graphics: the component graphics

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 boolean: indicates if the current styles should be merged with the new styles

paintBackground

public void paintBackground(Graphics g)

Exposing the background painting for the benefit of animations

Parameters

g Graphics: the form graphics

getTransitionInAnimator

public Transition getTransitionInAnimator()

This property allows us to define a an animation that will draw the transition for entering this form. A transition is an animation that would occur when switching from one form to another.

Returns

the Form in transition

setTransitionInAnimator

public void setTransitionInAnimator(Transition transitionInAnimator)

This property allows us to define a an animation that will draw the transition for entering this form. A transition is an animation that would occur when switching from one form to another.

Parameters

transitionInAnimator Transition: the Form in transition

getTransitionOutAnimator

public Transition getTransitionOutAnimator()

This property allows us to define a an animation that will draw the transition for exiting this form. A transition is an animation that would occur when switching from one form to another.

Returns

the Form out transition

setTransitionOutAnimator

public void setTransitionOutAnimator(Transition transitionOutAnimator)

This property allows us to define a an animation that will draw the transition for exiting this form. A transition is an animation that would occur when switching from one form to another.

Parameters

transitionOutAnimator Transition: the Form out transition

addCommandListener

public void addCommandListener(ActionListener l)

A listener that is invoked when a command is clicked allowing multiple commands to be handled by a single block

Parameters

l ActionListener: the command action listener

removeCommandListener

public void removeCommandListener(ActionListener l)

A listener that is invoked when a command is clicked allowing multiple commands to be handled by a single block

Parameters

l ActionListener: the command action listener

actionCommand

protected void actionCommand(Command cmd)

Invoked to allow subclasses of form to handle a command from one point rather than implementing many command instances. All commands selected on the form will trigger this method implicitly.

Parameters

cmd Command: the form commmand object

dispatchCommand

public void dispatchCommand(Command cmd, ActionEvent ev)

Dispatches a command via the standard form mechanism of firing a command event

Parameters

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

show

public void show()

Displays the current form on the screen

showBack

public void showBack()

Displays the current form on the screen, this version of the method is useful for “back” navigation since it reverses the direction of the transition.

addPointerPressedListener

public void addPointerPressedListener(ActionListener l)

Adds a listener to the pointer event

While this form’s listeners live on a host – which is the case for the whole time it is embedded, or hosted in a window – additions and removals have to go there too. The host’s pointer dispatch is what drives the hierarchy, so a listener added later (from onShow(), say) would sit in a dispatcher nothing consults, and removing a transferred one would leave it firing on the host.

Parameters

l ActionListener: callback to receive pointer events

removePointerPressedListener

public void removePointerPressedListener(ActionListener l)

Removes the listener from the pointer event

Parameters

l ActionListener: callback to remove

addPointerDraggedListener

public void addPointerDraggedListener(ActionListener l)

Adds a listener to the pointer event

Parameters

l ActionListener: callback to receive pointer events

removePointerDraggedListener

public void removePointerDraggedListener(ActionListener l)

Removes the listener from the pointer event

Parameters

l ActionListener: callback to remove

addPointerReleasedListener

public void addPointerReleasedListener(ActionListener l)

Adds a listener to the pointer event

Parameters

l ActionListener: callback to receive pointer events

removePointerReleasedListener

public void removePointerReleasedListener(ActionListener l)

Removes the listener from the pointer event

Parameters

l ActionListener: callback to remove

addLongPressListener

public void addLongPressListener(ActionListener l)

Adds a listener to the pointer event

Parameters

l ActionListener: callback to receive pointer events

removeLongPressListener

public void removeLongPressListener(ActionListener l)

Removes the listener from the pointer event

Parameters

l ActionListener: callback to remove

isSmoothScrolling

public boolean isSmoothScrolling()

Indicates that scrolling through the component should work as an animation

Returns

whether this component use smooth scrolling

setSmoothScrolling

public void setSmoothScrolling(boolean smoothScrolling)

Indicates that scrolling through the component should work as an animation

Parameters

smoothScrolling boolean: indicates if a component uses smooth scrolling

getScrollAnimationSpeed

public int getScrollAnimationSpeed()

Scroll animation speed in milliseconds allowing a developer to slow down or accelerate the smooth animation mode

Returns

scroll animation speed in milliseconds

setScrollAnimationSpeed

public void setScrollAnimationSpeed(int animationSpeed)

Scroll animation speed in milliseconds allowing a developer to slow down or accelerate the smooth animation mode

Parameters

animationSpeed int: scroll animation speed in milliseconds

onShow

protected void onShow()

Allows subclasses to bind functionality that occurs when a specific form or dialog appears on the screen

onShowCompleted

protected void onShowCompleted()

Allows subclasses to bind functionality that occurs when a specific form or dialog is “really” showing hence when the transition is totally complete (unlike onShow which is called on intent). The necessity for this is for special cases like media that might cause artifacts if played during a transition.

getComponentForm

public final Form getComponentForm()

Returns the Component Form or null if this Component is not added yet to a form

Returns

the Component Form

getTopLevelContainer

public TopLevelContainer getTopLevelContainer()

Returns the top level container this component currently belongs to, which is either the Form filling the main surface or the Window of a native desktop window, or null when this component is not attached to one.

Prefer this over #getComponentForm() in code that must keep working inside a desktop Window. getComponentForm() keeps its original meaning and returns null for a component hosted in a Window, because a Window is not a Form.

A Form terminates the walk unless it is itself embedded in another hierarchy, exactly as #getComponentForm() does.

Returns

the enclosing top level container, or null when detached

getFocused

public Component getFocused()

Returns the current focus component for this form

Returns

the current focus component for this form

setFocused

public void setFocused(Component focused)

Sets the focused component and fires the appropriate events to make it so

Parameters

focused Component: the newly focused component or null for no focus

longKeyPress

protected void longKeyPress(int keyCode)

If this Component is focused this method is invoked when the user presses and holds the key

Parameters

keyCode int: the key code value to indicate a physical key.

longPointerPress

public void longPointerPress(int x, int y)

If this Component is focused this method is invoked when the user presses and holds the pointer on the Component

shouldSendPointerReleaseToOtherForm

protected boolean shouldSendPointerReleaseToOtherForm()

Indicates whether this form wants to receive pointerReleased events for touch events that started in a different form

Returns

false by default

getNextComponent

public Component getNextComponent(Component current)

Gets the next component in focus traversal order. This will return the Component#getNextFocusRight() if it is set. If not, it will return Component#getNextFocusDown() if it is set. If not, it will return the next component according to the traversal order.

Parameters

current Component: The current component.

Returns

The next component in the focus traversal order.

getPreviousComponent

public Component getPreviousComponent(Component current)

Gets the previous component in focus traversal order. This will return the Component#getNextFocusLeft() if it is set. If not, it will return Component#getNextFocusUp() if it is set. If not, it will return the previous component according to the traversal order defined by Form#getTabIterator(com.codename1.ui.Component).

Parameters

current Component: The current component.

Returns

The previous component in the traversal order.

getTabIterator

public Form.TabIterator getTabIterator(Component start)

Returns an iterator that iterates over all of the components in this form, ordered by their tab index.

Parameters

start Component: The start position. The iterator will automatically initialized such that ListIterator#next() will return the next component in the traversal order, and the ListIterator#previous() returns the previous component in traversal order.

Returns

An iterator for the traversal order of the components in this form.

keyPressed

public void keyPressed(int keyCode)

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

Parameters

keyCode int: the key code value to indicate a physical key.

getLayout

public Layout getLayout()

Returns the layout manager of the form’s content pane.

Returns

the container layout manager

setLayout

public void setLayout(Layout layout)

Sets the layout manager responsible for arranging this container

Parameters

layout Layout: the specified layout manager

isMinimizeOnBack

public boolean isMinimizeOnBack()

When set to true the physical back button will minimize the application

Returns

the minimizeOnBack

setMinimizeOnBack

public void setMinimizeOnBack(boolean minimizeOnBack)

When set to true the physical back button will minimize the application

Parameters

minimizeOnBack boolean: the minimizeOnBack to set

keyReleased

public void keyReleased(int keyCode)

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

Parameters

keyCode int: the key code value to indicate a physical key.

keyRepeated

public void keyRepeated(int keyCode)

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

Parameters

keyCode int: the key code value to indicate a physical key.

resumeDragAfterScrolling

protected boolean resumeDragAfterScrolling(int x, int y)

This method fixes this tensile drag issue. However, this might be undesireable in some cases and so this method can be overriden to return false in some cases.

Parameters

x int: the x position of a pointer press operation
y int: the y position of a pointer press operation

Returns

true if drag should be resumed and false otherwise

pointerPressed

public void pointerPressed(int x, int y)

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

Parameters

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

addComponentAwaitingRelease

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

pointerDragged

public void pointerDragged(int x, int y)

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

Parameters

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

pointerDragged

public void pointerDragged(int[] x, int[] y)

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

Parameters

x int[]: the pointer x coordinate
y int[]: the pointer y coordinate

pointerHoverReleased

public void pointerHoverReleased(int[] x, int[] y)

Invoked for devices where the pointer can hover without actually clicking the display. This is true for PC mouse pointer as well as some devices such as the BB storm.

Parameters

x int[]: the pointer x coordinate
y int[]: the pointer y coordinate

pointerHoverPressed

public void pointerHoverPressed(int[] x, int[] y)

Invoked for devices where the pointer can hover without actually clicking the display. This is true for PC mouse pointer as well as some devices such as the BB storm.

Parameters

x int[]: the pointer x coordinate
y int[]: the pointer y coordinate

pointerHover

public void pointerHover(int[] x, int[] y)

Invoked for devices where the pointer can hover without actually clicking the display. This is true for PC mouse pointer as well as some devices such as the BB storm.

Parameters

x int[]: the pointer x coordinate
y int[]: the pointer y coordinate

isSingleFocusMode

public boolean isSingleFocusMode()

Returns true if there is only one focusable member in this form. This is useful so setHandlesInput would always be true for this case.

Returns

true if there is one focusable component in this form, false for 0 or more

pointerReleased

public void pointerReleased(int x, int y)

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

Parameters

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

isScrollVisible

public boolean isScrollVisible()

Indicate whether this component scroll is visible

Returns

true is this component scroll is visible; otherwise false

setScrollVisible

public void setScrollVisible(boolean isScrollVisible)

Set whether this component scroll is visible

Parameters

isScrollVisible boolean: Indicate whether this component scroll is visible

getComponentIndex

public int getComponentIndex(Component cmp)

Returns the Component index in the Container

Parameters

cmp Component: the component to search for

Returns

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

addCommand

public void addCommand(Command cmd, int offset)

Deprecated. Please use Toolbar#addCommandToLeftBar(com.codename1.ui.Command) or similar methods

Adds a command to the menu bar softkeys or into the menu dialog, this version of add allows us to place a command in an arbitrary location. This allows us to force a command into the softkeys when order of command addition can’t be changed.

Parameters

cmd Command: the Form command to be added
offset int: position in which the command is added

getCommandCount

public int getCommandCount()

Deprecated. Please use Toolbar#getComponentCount() or similar methods

A helper method to check the amount of commands within the form menu

Returns

the number of commands

getCommand

public Command getCommand(int index)

Returns the command occupying the given index

Parameters

index int: offset of the command

Returns

the command at the given index

addCommand

public final void addCommand(Command cmd)

Deprecated. Please use Toolbar#addCommandToLeftBar(com.codename1.ui.Command) or similar methods

Adds a command to the menu bar softkeys. The Commands are placed in the order they are added. If the Form has 1 Command it will be placed on the right. If the Form has 2 Commands the first one that was added will be placed on the right and the second one will be placed on the left. If the Form has more then 2 Commands the first one will stay on the left and a Menu will be added with all the remain Commands.

Parameters

cmd Command: the Form command to be added

removeCommand

public void removeCommand(Command cmd)

Removes the command from the menu bar softkeys

Parameters

cmd Command: the Form command to be removed

findNextFocusVertical

public Component findNextFocusVertical(boolean down)

This method returns the next focusable Component vertically

NOTE: This method does NOT make use of Component#getNextFocusDown() or Component#getNextFocusUp(). It simply finds the next focusable component on the form based solely on absolute Y coordinate.

Parameters

down boolean: if true will the return the next focusable on the bottom else on the top

Returns

a focusable Component or null if not found

findNextFocusHorizontal

public Component findNextFocusHorizontal(boolean right)

This method returns the next focusable Component horizontally

NOTE: This method does NOT make use of Component#getNextFocusLeft() or Component#getNextFocusRight(). It simply finds the next focusable component on the form based solely on absolute X coordinate.

Parameters

right boolean: if true will the return the next focusable on the right else on the left

Returns

a focusable Component or null if not found

isCyclicFocus

public boolean isCyclicFocus()

Indicates whether focus should cycle within the form

Returns

true if focus should cycle

setCyclicFocus

public void setCyclicFocus(boolean cyclicFocus)

Indicates whether focus should cycle within the form

Parameters

cyclicFocus boolean: marks whether focus should cycle

scrollComponentToVisible

public void scrollComponentToVisible(Component c)

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

Parameters

c Component: the componant to be visible

setMenuCellRenderer

public void setMenuCellRenderer(ListCellRenderer menuCellRenderer)

Determine the cell renderer used to render menu elements for themeing the look of the menu options

Parameters

menuCellRenderer ListCellRenderer: the menu cell renderer

removeAllCommands

public void removeAllCommands()

Clear menu commands from the menu bar

setRTL

public void setRTL(boolean r)

Is the component a bidi RTL component

Parameters

r boolean: true if the component should work in a right to left mode

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 Graphics: the component graphics

isScrollable

public boolean isScrollable()

Indicates whether the component should/could scroll by default a component is not scrollable.

Returns

whether the component is scrollable

setScrollable

public void setScrollable(boolean scrollable)

The equivalent of calling both setScrollableY and setScrollableX

Parameters

scrollable boolean: whether the component should/could scroll on the X and Y axis

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

setScrollableX

public void setScrollableX(boolean scrollableX)

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

Parameters

scrollableX boolean: 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

setScrollableY

public void setScrollableY(boolean scrollableY)

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

Parameters

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

setVisible

public void setVisible(boolean visible)

Toggles visibility of the component

Parameters

visible boolean: true if component is visible; otherwise false

getTintColor

public int getTintColor()

Default color for the screen tint when a dialog or a menu is shown

Returns

the tint color when a dialog or a menu is shown

setTintColor

public void setTintColor(int tintColor)

Default color for the screen tint when a dialog or a menu is shown

Parameters

tintColor int: the tint color when a dialog or a menu is shown

setMenuTransitions

public void setMenuTransitions(Transition transitionIn, Transition transitionOut)

Sets the menu transitions for showing/hiding the menu, can be null…

Parameters

transitionIn Transition: the transition that will play when the menu appears
transitionOut Transition: the transition that will play when the menu is folded

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

getMenuBar

public MenuBar getMenuBar()

Returns the associated Menu Bar object

Returns

the associated Menu Bar object

setMenuBar

public void setMenuBar(MenuBar menuBar)

Sets the associated MenuBar Object.

setToolBar

public void setToolBar(Toolbar toolbar)

Deprecated. use setToolbar instead (lower case b)

Sets the Form Toolbar

getToolbar

public Toolbar getToolbar()

Gets the Form Toolbar if exists or null

Returns

the Toolbar instance or null if does not exists.

setToolbar

public void setToolbar(Toolbar toolbar)

Sets the Form Toolbar

isFocusScrolling

public boolean isFocusScrolling()

Indicates whether lists and containers should scroll only via focus and thus “jump” when moving to a larger component as was the case in older versions of Codename One.

Returns

the value of focusScrolling

setFocusScrolling

public void setFocusScrolling(boolean focusScrolling)

Indicates whether lists and containers should scroll only via focus and thus “jump” when moving to a larger component as was the case in older versions of Codename One.

Parameters

focusScrolling boolean: the new value for focus scrolling

getPropertyNames

public String[] getPropertyNames()

A component may expose mutable property names for a UI designer to manipulate, this API is designed for usage internally by the GUI builder code

Returns

the property names allowing mutation

getPropertyTypes

public Class[] getPropertyTypes()

Matches the property names method (see that method for further details).

Returns

the types of the properties

getPropertyTypeNames

public String[] getPropertyTypeNames()

This method is here to workaround an XMLVM array type bug where property types aren’t identified properly, it returns the names of the types using the following type names: String,int,double,long,byte,short,char,String[],String[][],byte[],Image,Image[],Object[],ListModel,ListCellRenderer

Returns

Array of type names

getPropertyValue

public Object getPropertyValue(String name)

Returns the current value of the property name, this method is used by the GUI builder

Parameters

name String: the name of the property

Returns

the value of said property

setPropertyValue

public String setPropertyValue(String name, Object value)

Sets a new value to the given property, returns an error message if failed and null if successful. Notice that some builtin properties such as “$designMode” might be sent to components to indicate application state.

Parameters

name String: the name of the property
value Object: new value for the property

Returns

error message or null

getEditOnShow

public TextArea getEditOnShow()

A text component that will receive focus and start editing immediately as the form is shown

Returns

the component instance

setEditOnShow

public void setEditOnShow(TextArea editOnShow)

A text component that will receive focus and start editing immediately as the form is shown

Parameters

editOnShow TextArea: text component to edit when the form is shown

Nested types

Fields

Constructors

Methods

Inherited fields

From Component

Inherited methods

From Container

From Component

From Object

From Iterable

Field details

focusScrolling

Constructor details

Form

Form

Parameters

Form

Parameters

Form

Parameters

Method details

setAllowEnableLayoutOnPaint

Parameters

addPasteListener

Parameters

removePasteListener

Parameters

See also

dispatchPaste

Parameters

See also

getTextSelection

Returns

isEnableCursors

Returns

See also

setEnableCursors

Parameters

See also

getSourceCommand

Returns

setSourceCommand

Parameters

getCurrentInputDevice

Returns

See also

setCurrentInputDevice

Throws

initGlobalToolbar

setOverrideInvisibleAreaUnderVKB

Parameters

getInvisibleAreaUnderVKB

Returns

See also

getAnimationManager

Returns

isFormBottomPaddingEditingMode

Returns

setFormBottomPaddingEditingMode

Parameters

getSafeArea

Returns

See also

shouldPaintStatusBar

Returns

createStatusBar

Returns

isAlwaysTensile

Returns

setAlwaysTensile

Parameters

grabAnimationLock

Returns

releaseAnimationLock

findCurrentlyEditingComponent

Returns

See also

getTitleArea

Returns