# Class UIBuilder

java.lang.Object
com.codename1.ui.util.UIBuilder

public class UIBuilder extends java.lang.Object
The UI builder can create a user interface based on the UI designed in the resource editor and allows us to bind to said UI. Notice that if a Component was used in the GUI that is not a part of the com.codename1.ui package (even a Component from sub packages such as table or tree) it MUST be registered before loading a GUI!

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `BACK_COMMAND_ID`
  `static final String`
  `FORM_STATE_KEY_FOCUS`
  A key in the form state hashtable used in the back command navigation
  `static final String`
  `FORM_STATE_KEY_NAME`
  A key in the form state hashtable used in the back command navigation
  `static final String`
  `FORM_STATE_KEY_SELECTION`
  A key in the form state hashtable used in the back command navigation
  `static final String`
  `FORM_STATE_KEY_TITLE`
  A key in the form state hashtable used in the back command navigation

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UIBuilder()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addCommandListener(ActionListener l)`
  Adds a command listener that would be bound to all forms in the GUI seamlessly
  `void`
  `addCommandListener(String formName, ActionListener l)`
  Adds a command listener to be invoked for commands on a specific form
  `void`
  `addComponentListener(String formName, String componentName, java.lang.Object listener)`
  Adds a component listener that would be bound when a UI for this form is created.
  `protected boolean`
  `allowBackTo(String formName)`
  Indicates whether a back command to this form should be generated automatically when leaving said form.
  `protected void`
  `analyticsCallback(String page, String referrer)`
  Invokes the analytics service if it is enabled and if
  `protected void`
  `asyncCommandProcess(Command cmd, ActionEvent sourceEvent)`
  Warning: This method is invoked OFF the EDT and is intended for usage with asynchronous command processing.
  `void`
  `back()`
  This method effectively pops the form navigation stack and goes back to the previous form if back navigation is enabled and there is a previous form.
  `void`
  `back(Component sourceComponent)`
  This method effectively pops the form navigation stack and goes back to the previous form if back navigation is enabled and there is a previous form.
  `protected void`
  `beforeShow(Form f)`
  This method allows binding an action that should occur before showing the given form
  `protected void`
  `beforeShowContainer(Container c)`
  This method allows binding an action that should occur before showing the given container
  `protected void`
  `bindListenerToComponent(Component cmp, java.lang.Object listener)`
  Binds the given listener object to the component, this works seamlessly for common Codename One events but might be an issue with custom components and custom listener types so this method can be overloaded to add support for such cases.
  `LazyValue<Form>`
  `createBackLazyValue(Form f)`
  This is useful for swipe back navigation behavior
  `protected Command`
  `createCommand(String commandName, Image icon, int commandId, String action)`
  Creates a command instance.
  `protected Component`
  `createComponentInstance(String componentType, java.lang.Class cls)`
  This method can be overriden to create custom components in a custom way, the component type is a shorthand for the component name and not the full name of the class.
  `Container`
  `createContainer(Resources res, String resourceName)`
  Creates the container defined under the given name in the res file
  `Container`
  `createContainer(String resPath, String resourceName)`
  Creates the container defined under the given name in the res file
  `protected void`
  `exitForm(Form f)`
  This method allows binding an action that should occur before leaving the given form, e.g.
  `protected Resources`
  `fetchResourceFile()`
  This method may be overriden by subclasses to provide a way to dynamically load a resource file.
  `Component`
  `findByName(String name, Component rootComponent)`
  Finds the given component by its name
  `Component`
  `findByName(String name, Container rootComponent)`
  Finds the given component by its name
  `protected String`
  `formNavigationStackDebug()`
  Useful method for logging form navigation, it returns a string representing the navigation state which can be used to analyze crash reports
  `protected String`
  `getBackCommandText(String previousFormTitle)`
  Returns the text for the back command string.
  `protected Hashtable`
  `getContainerState(Container cnt)`
  This method is the container navigation equivalent of getFormState() see that method for details.
  `protected Hashtable`
  `getFormState(Form f)`
  Returns the state of the current form which we are about to leave as part of the navigation logic.
  `String`
  `getHomeForm()`
  When reaching the home form the navigation stack is cleared
  `String`
  `getResourceFilePath()`
  Allows the navigation code to avoid storing the resource file and lets the GC remove it from memory when its not in use
  `protected Container`
  `getRootAncestor(Component c)`
  Returns either the parent form or the component below the embedded container above c.
  `protected void`
  `handleComponentAction(Component c, ActionEvent event)`
  This method is invoked for every component to which an action event listener can be bound and delivers the event data for the given component seamlessly.
  `boolean`
  `isBackCommandEnabled()`
  Seamlessly inserts a back command to all the forms
  `static boolean`
  `isBlockAnalytics()`
  Enables blocking analytics in the UIBuilder, this is useful for the designer tool.
  `boolean`
  `isKeepResourcesInRam()`
  Indicates that the UIBuilder should cache resources in memory and never release them.
  `protected boolean`
  `isSameBackDestination(Container source, Container destination)`
  When navigating from one form/container to another we sometimes might not want the back command to return to the previous container/form but rather to the one before source.
  `protected void`
  `onBackNavigation()`
  This callback is invoked to indicate that the upcoming form is shown as part of a "back" navigation.
  `protected void`
  `onCreateRoot(String rootName)`
  This method allows binding logic that should occur before creating the root object e.g.
  `protected void`
  `popNavigationStack()`
  Removes a navigation frame from the stack, this is useful in case you want to go back to a form in the middle of the navigation stack.
  `protected void`
  `postAsyncCommand(Command cmd, ActionEvent sourceEvent)`
  This method is invoked in conjunction with asyncCommandProcess after the command was handled asynchronously on the separate thread.
  `protected void`
  `postCreateComponent(Component cmp)`
  Callback to allow binding custom logic/listeners to a component after its major properties were set (notice that not all properties or the full hierarchy will be available at this stage).
  `protected void`
  `postShow(Form f)`
  This method allows binding an action that should occur immediately after showing the given form
  `protected void`
  `postShowContainer(Container c)`
  This method allows binding an action that should occur immediately after showing the given container
  `protected boolean`
  `processBackground(Form f)`
  Warning: this method is invoked on a separate thread.
  `protected void`
  `processCommand(ActionEvent ev, Command cmd)`
  Invoked to process a given command before naviation or any other internal processing occurs.
  `static void`
  `registerCustomComponent(String name, java.lang.Class cmp)`
  This method allows the UIBuilder to package a smaller portion of Codename One into the JAR and add support for additional 3rd party components to the GUI builder.
  `void`
  `reloadContainer(Component cnt)`
  Useful tool to refresh the current state of a container shown using show container without pushing another instance to the back stack
  `void`
  `reloadForm()`
  Useful tool to refresh the current state of a form shown using show form without pushing another instance to the back stack
  `void`
  `removeCommandListener(ActionListener l)`
  Removes a command listener
  `void`
  `removeCommandListener(String formName, ActionListener l)`
  Removes a command listener on a specific form
  `void`
  `removeComponentListener(String formName, String componentName, java.lang.Object listener)`
  Removes a component listener bound to a specific component
  `protected void`
  `restoreComponentState(Component c, Hashtable destination)`
  By default Codename One stores the states of components in the navigation graph as it moves between forms.
  `protected void`
  `setBackCommand(Form f, Command backCommand)`
  Invoked internally to set the back command on the form, this method allows subclasses to change the behavior of back command adding or disable it
  `void`
  `setBackCommandEnabled(boolean back)`
  Seamlessly inserts a back command to all the forms
  `protected void`
  `setBackDestination(String formName)`
  Pops the navigation stack until it finds form name and the back button will match form name if form name isn't in the stack this method will fail
  `static void`
  `setBlockAnalytics(boolean aBlockAnalytics)`
  Enables blocking analytics in the UIBuilder, this is useful for the designer tool.
  `protected void`
  `setContainerState(Container cnt, Hashtable state)`
  This method is the container navigation equivalent of setFormState() see that method for details.
  `protected void`
  `setFormState(Form f, Hashtable state)`
  Sets the state of the current form to which we are returing as part of the navigation logic.
  `void`
  `setHomeForm(String homeForm)`
  When reaching the home form the navigation stack is cleared
  `void`
  `setKeepResourcesInRam(boolean keepResourcesInRam)`
  Indicates that the UIBuilder should cache resources in memory and never release them.
  `protected boolean`
  `setListModel(List cmp)`
  Allows a subclass to set the list model for the given component
  `protected boolean`
  `setListModel(ContainerList cmp)`
  Allows a subclass to set the list model for the given component
  `protected void`
  `setResourceFile(Resources res)`
  Sets the resource file if keep in rum or no path is defined
  `void`
  `setResourceFilePath(String resourceFilePath)`
  Allows the navigation code to avoid storing the resource file and lets the GC remove it from memory when its not in use
  `protected boolean`
  `shouldAddBackCommandToMenu()`
  Back commands are set implicitly (see allowBackTo to disable that), this method allows subclasses to disable the behavior where the back command is also added to the menu (not just set to the back button).
  `protected boolean`
  `shouldAutoStoreState()`
  Indicates whether the UIBuilder should try storing states for forms on its own by seeking lists, tabs and other statefull elements and keeping their selection
  `Container`
  `showContainer(String resourceName, Command sourceCommand, Component sourceComponent)`
  This method is equivalent to the internal navigation behavior, it adds functionality such as the back command into the given form resource and shows it.
  `Form`
  `showForm(String resourceName, Command sourceCommand)`
  This method is equivalent to the internal navigation behavior, it adds functionality such as the back command into the given form resource and shows it.
  `protected void`
  `storeComponentState(Component c, Hashtable destination)`
  By default Codename One stores the states of components in the navigation graph as it moves between forms.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### FORM_STATE_KEY_NAME

    public static final String FORM_STATE_KEY_NAME
    A key in the form state hashtable used in the back command navigation
    See Also:
      - Constant Field Values

  - ### FORM_STATE_KEY_TITLE

    public static final String FORM_STATE_KEY_TITLE
    A key in the form state hashtable used in the back command navigation
    See Also:
      - Constant Field Values

  - ### FORM_STATE_KEY_FOCUS

    public static final String FORM_STATE_KEY_FOCUS
    A key in the form state hashtable used in the back command navigation
    See Also:
      - Constant Field Values

  - ### FORM_STATE_KEY_SELECTION

    public static final String FORM_STATE_KEY_SELECTION
    A key in the form state hashtable used in the back command navigation
    See Also:
      - Constant Field Values

  - ### BACK_COMMAND_ID

    public static final int BACK_COMMAND_ID
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### UIBuilder

    public UIBuilder()

- ## Method Details

  - ### isBlockAnalytics

    public static boolean isBlockAnalytics()

    Enables blocking analytics in the UIBuilder, this is useful for the designer tool.

    ###### Returns

    the blockAnalytics

  - ### setBlockAnalytics

    public static void setBlockAnalytics(boolean aBlockAnalytics)

    Enables blocking analytics in the UIBuilder, this is useful for the designer tool.

    ###### Parameters

    - `aBlockAnalytics`: the blockAnalytics to set

  - ### registerCustomComponent

    public static void registerCustomComponent(String name, java.lang.Class cmp)

    This method allows the UIBuilder to package a smaller portion of Codename One into the JAR and add support for additional 3rd party components to the GUI builder. Components must be registered using their UIID name, by default all the content of com.codename1.ui is registered however subpackages and 3rd party components are not. Registration is essential for obfuscation to work properly!

    ###### Parameters

    - `name`: the name of the component (UIID)

    - `cmp`: the class for the given component

  - ### popNavigationStack

    protected void popNavigationStack()
    Removes a navigation frame from the stack, this is useful in case you want to go back to a form in the middle of the navigation stack.

  - ### setBackDestination

    protected void setBackDestination(String formName)

    Pops the navigation stack until it finds form name and the back button will match form name if form name isn't in the stack this method will fail

    ###### Parameters

    - `formName`: the name of the form to navigate back to.

  - ### formNavigationStackDebug

    protected String formNavigationStackDebug()

    Useful method for logging form navigation, it returns a string representing the navigation state which can be used to analyze crash reports

    ###### Returns

    A string representing form states

  - ### isBackCommandEnabled

    public boolean isBackCommandEnabled()

    Seamlessly inserts a back command to all the forms

    ###### Returns

    true if a back command is automatically added

  - ### setBackCommandEnabled

    public void setBackCommandEnabled(boolean back)

    Seamlessly inserts a back command to all the forms

    ###### Parameters

    - `back`: true to automatically add a back command

  - ### analyticsCallback

    protected void analyticsCallback(String page, String referrer)

    Invokes the analytics service if it is enabled and if

    ###### Parameters

    - `page`: the page visited

    - `referrer`: the source page

  - ### createContainer

    public Container createContainer(String resPath, String resourceName)

    Creates the container defined under the given name in the res file

    ###### Parameters

    - `resPath`: the path to the res file containing the UI widget

    - `resourceName`: the name of the widget in the res file

    ###### Returns

    a Codename One container instance

  - ### createContainer

    public Container createContainer(Resources res, String resourceName)

    Creates the container defined under the given name in the res file

    ###### Parameters

    - `res`: the res file containing the UI widget

    - `resourceName`: the name of the widget in the res file

    ###### Returns

    a Codename One container instance

  - ### findByName

    public Component findByName(String name, Component rootComponent)

    Finds the given component by its name

    ###### Parameters

    - `name`: the name of the component as defined in the resource editor

    - `rootComponent`: the root container

    ###### Returns

    the component matching the given name or null if its not found

  - ### findByName

    public Component findByName(String name, Container rootComponent)

    Finds the given component by its name

    ###### Parameters

    - `name`: the name of the component as defined in the resource editor

    - `rootComponent`: the root container

    ###### Returns

    the component matching the given name or null if its not found

  - ### createComponentInstance

    protected Component createComponentInstance(String componentType, java.lang.Class cls)

    This method can be overriden to create custom components in a custom way, the component type is a shorthand for the component name and not the full name of the class. By default this method returns null which indicates Codename One should try to reolve the component on its own.

    ###### Parameters

    - `componentType`: the type of the component from the UI builder

    - `cls`: assumed component class based on the component registry

    ###### Returns

    a new component instance or null

  - ### postCreateComponent

    protected void postCreateComponent(Component cmp)

    Callback to allow binding custom logic/listeners to a component after its major properties were set (notice that not all properties or the full hierarchy will be available at this stage). This is the perfect place to bind models/renderers etc. to components.

    ###### Parameters

    - `cmp`: the component

  - ### bindListenerToComponent

    protected void bindListenerToComponent(Component cmp, java.lang.Object listener)

    Binds the given listener object to the component, this works seamlessly for common Codename One events but might be an issue with custom components and custom listener types so this method can be overloaded to add support for such cases.

    ###### Parameters

    - `cmp`: the component to bind the listener to

    - `listener`: the listener object

  - ### setListModel

    protected boolean setListModel(List cmp)

    Allows a subclass to set the list model for the given component

    ###### Parameters

    - `cmp`: the list whose model may be set

    ###### Returns

    true if a model was set by this method

  - ### setListModel

    protected boolean setListModel(ContainerList cmp)

    Allows a subclass to set the list model for the given component

    ###### Parameters

    - `cmp`: the list whose model may be set

    ###### Returns

    true if a model was set by this method

  - ### createCommand

    protected Command createCommand(String commandName, Image icon, int commandId, String action)

    Creates a command instance. This method is invoked by the loading code and can be overriden to create a subclass of the Command class.

    ###### Parameters

    - `commandName`: the label on the command

    - `icon`: the icon for the command

    - `commandId`: the id of the command

    - `action`: the action assigned to the command if such an action is defined

    ###### Returns

    a new command instance

  - ### fetchResourceFile

    protected Resources fetchResourceFile()

    This method may be overriden by subclasses to provide a way to dynamically load a resource file. Normally the navigation feature of the UIBuilder requires the resource file present in RAM. However, that might be expensive to maintain. By implementing this method and replacing the storeResourceFile() with an empty implementation the resource file storage can be done strictly in RAM.

    ###### Returns

    the instance of the resource file

  - ### getResourceFilePath

    public String getResourceFilePath()

    Allows the navigation code to avoid storing the resource file and lets the GC remove it from memory when its not in use

    ###### Returns

    the resourceFilePath

  - ### setResourceFilePath

    public void setResourceFilePath(String resourceFilePath)

    Allows the navigation code to avoid storing the resource file and lets the GC remove it from memory when its not in use

    ###### Parameters

    - `resourceFilePath`: the resourceFilePath to set

  - ### setResourceFile

    protected void setResourceFile(Resources res)

    Sets the resource file if keep in rum or no path is defined

    ###### Parameters

    - `res`: the resource file

  - ### processCommand

    protected void processCommand(ActionEvent ev, Command cmd)

    Invoked to process a given command before naviation or any other internal processing occurs. The event can be consumed to prevent further processing.

    ###### Parameters

    - `ev`: the action event source of the command

    - `cmd`: the command to process

  - ### addCommandListener

    public void addCommandListener(ActionListener l)

    Adds a command listener that would be bound to all forms in the GUI seamlessly

    ###### Parameters

    - `l`: the listener to bind

  - ### removeCommandListener

    public void removeCommandListener(ActionListener l)

    Removes a command listener

    ###### Parameters

    - `l`: the listener to remove

  - ### addComponentListener

    public void addComponentListener(String formName, String componentName, java.lang.Object listener)

    Adds a component listener that would be bound when a UI for this form is created. Notice that this method is only effective before the form was created and would do nothing for an existing form

    ###### Parameters

    - `formName`: the name of the form to which the listener should be bound

    - `componentName`: the name of the component to bind to

    - `listener`: the listener to bind, common listener types are supported

  - ### removeComponentListener

    public void removeComponentListener(String formName, String componentName, java.lang.Object listener)

    Removes a component listener bound to a specific component

    ###### Parameters

    - `formName`: the name of the form

    - `componentName`: the name of the component

    - `listener`: the listener instance

  - ### addCommandListener

    public void addCommandListener(String formName, ActionListener l)

    Adds a command listener to be invoked for commands on a specific form

    ###### Parameters

    - `formName`: the name of the form to which the listener should be bound

    - `l`: the listener to bind

  - ### removeCommandListener

    public void removeCommandListener(String formName, ActionListener l)

    Removes a command listener on a specific form

    ###### Parameters

    - `formName`: the name of the form

    - `l`: the listener to remove

  - ### handleComponentAction

    protected void handleComponentAction(Component c, ActionEvent event)

    This method is invoked for every component to which an action event listener can be bound and delivers the event data for the given component seamlessly.

    ###### Parameters

    - `c`: the component broadcasting the event

    - `event`: the event meta data

  - ### asyncCommandProcess

    protected void asyncCommandProcess(Command cmd, ActionEvent sourceEvent)

    Warning: This method is invoked OFF the EDT and is intended for usage with asynchronous command processing. This method is invoked when the UI indicates that an operation should occur in the background. To finish the processing of the operation within the EDT one should override the postAsyncCommand() method.

    ###### Parameters

    - `cmd`: the command requiring background processing

    - `sourceEvent`: the triggering event

  - ### postAsyncCommand

    protected void postAsyncCommand(Command cmd, ActionEvent sourceEvent)

    This method is invoked in conjunction with asyncCommandProcess after the command was handled asynchronously on the separate thread. Here Codename One code can be execute to update the UI with the results from the separate thread.

    ###### Parameters

    - `cmd`: the command

    - `sourceEvent`: the source event

  - ### processBackground

    protected boolean processBackground(Form f)

    Warning: this method is invoked on a separate thread. This method is invoked when a next form property is defined, this property indicates a background process for a form of a transitional nature should take place (e.g. splash screen, IO etc.) after which the next form should be shown. After this method completes the next form is shown.

    ###### Parameters

    - `f`: @param f the form for which the background thread was constructed, notice that most methods are not threadsafe and one should use callSerially* in this method when mutating the form.

    ###### Returns

    Returns:
      if false is returned from this method navigation should not proceed to that given form

  - ### getFormState

    protected Hashtable getFormState(Form f)

    Returns the state of the current form which we are about to leave as part of the navigation logic. When a back command will return to this form the state would be restored using setFormState. The default implementation of this method restores focus and list selection. You can add arbitrary keys to the form state, keys starting with a $ sign are reserved for the UIBuilder base class use.

    ###### Parameters

    - `f`: the form whose state should be preserved

    ###### Returns

    arbitrary state object

  - ### restoreComponentState

    protected void restoreComponentState(Component c, Hashtable destination)

    By default Codename One stores the states of components in the navigation graph as it moves between forms. However, some components aren't recognized by Codename One by default to enable smaller executable size. This method can be overriden to enable storing the state of custom components

    ###### Parameters

    - `c`: the component whose state should be restored

    - `destination`: the hashtable containing the state

  - ### storeComponentState

    protected void storeComponentState(Component c, Hashtable destination)

    By default Codename One stores the states of components in the navigation graph as it moves between forms. However, some components aren't recognized by Codename One by default to enable smaller executable size. This method can be overriden to enable storing the state of custom components

    ###### Parameters

    - `c`: the component whose state should be stored

    - `destination`: the destination hashtable

  - ### shouldAutoStoreState

    protected boolean shouldAutoStoreState()

    Indicates whether the UIBuilder should try storing states for forms on its own by seeking lists, tabs and other statefull elements and keeping their selection

    ###### Returns

    true to handle state automatically, false otherwise

  - ### setFormState

    protected void setFormState(Form f, Hashtable state)

    Sets the state of the current form to which we are returing as part of the navigation logic. When a back command is pressed this form state should be restored, it was obtained via getFormState. The default implementation of this method restores focus and list selection.

    ###### Parameters

    - `f`: the form whose state should be preserved

    - `state`: arbitrary state object

  - ### getContainerState

    protected Hashtable getContainerState(Container cnt)

    This method is the container navigation equivalent of getFormState() see that method for details.

    ###### Parameters

    - `cnt`: the container

    ###### Returns

    the state

  - ### setContainerState

    protected void setContainerState(Container cnt, Hashtable state)

    This method is the container navigation equivalent of setFormState() see that method for details.

    ###### Parameters

    - `cnt`: the container

    - `state`: the state

  - ### getHomeForm

    public String getHomeForm()

    When reaching the home form the navigation stack is cleared

    ###### Returns

    the homeForm

  - ### setHomeForm

    public void setHomeForm(String homeForm)

    When reaching the home form the navigation stack is cleared

    ###### Parameters

    - `homeForm`: the homeForm to set

  - ### back

    public void back()
    This method effectively pops the form navigation stack and goes back to the previous form if back navigation is enabled and there is a previous form.

  - ### back

    public void back(Component sourceComponent)

    This method effectively pops the form navigation stack and goes back to the previous form if back navigation is enabled and there is a previous form.

    ###### Parameters

    - `sourceComponent`: @param sourceComponent the component that triggered the back command which effectively allows us to find the EmbeddedContainer for a case of container navigation. Null can be used if not applicable.

  - ### getBackCommandText

    protected String getBackCommandText(String previousFormTitle)

    Returns the text for the back command string. This can be controlled in the theme by the "backUsesTitleBool" constant

    ###### Parameters

    - `previousFormTitle`: the title of the previous form

    ###### Returns

    the string for the back command inserted implicitly

  - ### setBackCommand

    protected void setBackCommand(Form f, Command backCommand)

    Invoked internally to set the back command on the form, this method allows subclasses to change the behavior of back command adding or disable it

    ###### Parameters

    - `f`: the form

    - `backCommand`: the back command

  - ### showContainer

    public Container showContainer(String resourceName, Command sourceCommand, Component sourceComponent)

    This method is equivalent to the internal navigation behavior, it adds functionality such as the back command into the given form resource and shows it. If the source command is the back command the showBack() method will run. Notice that container navigation (none-form) doesn't support the back() method or the form stack. However a command marked as back command will be respected.

    ###### Parameters

    - `resourceName`: the name of the resource for the form to show

    - `sourceCommand`: the command of the resource (may be null)

    - `sourceComponent`: the component that activated the show (may be null)

    ###### Returns

    Returns:
      the container thats being shown, notice that you can still manipulate some states of the container before it actually appears

  - ### reloadContainer

    public void reloadContainer(Component cnt)

    Useful tool to refresh the current state of a container shown using show container without pushing another instance to the back stack

    ###### Parameters

    - `cnt`: the container thats embedded into the application

  - ### reloadForm

    public void reloadForm()
    Useful tool to refresh the current state of a form shown using show form without pushing another instance to the back stack

  - ### createBackLazyValue

    public LazyValue<Form> createBackLazyValue(Form f)

    This is useful for swipe back navigation behavior

    ###### Parameters

    - `f`: the form from which we should go back

    ###### Returns

    a lazy value that will return the back form

  - ### allowBackTo

    protected boolean allowBackTo(String formName)

    Indicates whether a back command to this form should be generated automatically when leaving said form.

    ###### Parameters

    - `formName`: the name of the form

    ###### Returns

    true to autogenerate and add a back command to the destination form

  - ### isSameBackDestination

    protected boolean isSameBackDestination(Container source, Container destination)

    When navigating from one form/container to another we sometimes might not want the back command to return to the previous container/form but rather to the one before source. A good example would be a "refresh" command or a toggle button that changes the form state.

    ###### Parameters

    - `source`: the form or container we are leaving

    - `destination`: the container or form we are navigating to

    ###### Returns

    Returns:
      false if we want a standard back button to source, true if we want to use the same back button as the one in source

  - ### showForm

    public Form showForm(String resourceName, Command sourceCommand)

    This method is equivalent to the internal navigation behavior, it adds functionality such as the back command into the given form resource and shows it. If the source command is the back command the showBack() method will run.

    ###### Parameters

    - `resourceName`: the name of the resource for the form to show

    - `sourceCommand`: the command of the resource (may be null)

    ###### Returns

    Returns:
      the form thats being shown, notice that you can still manipulate some states of the form before it actually appears

  - ### exitForm

    protected void exitForm(Form f)

    This method allows binding an action that should occur before leaving the given form, e.g. memory cleanup

    ###### Parameters

    - `f`: the form being left

  - ### beforeShow

    protected void beforeShow(Form f)

    This method allows binding an action that should occur before showing the given form

    ###### Parameters

    - `f`: the form about to be shown

  - ### onBackNavigation

    protected void onBackNavigation()
    This callback is invoked to indicate that the upcoming form is shown as part of a "back" navigation. This is useful for the case of a breadcrumb UI where the navigation stack is shown at the top of the UI, in that case this method can be used to pop out the breadcrumb stack.

  - ### shouldAddBackCommandToMenu

    protected boolean shouldAddBackCommandToMenu()
    Back commands are set implicitly (see allowBackTo to disable that), this method allows subclasses to disable the behavior where the back command is also added to the menu (not just set to the back button).

  - ### postShow

    protected void postShow(Form f)

    This method allows binding an action that should occur immediately after showing the given form

    ###### Parameters

    - `f`: the form that was just shown

  - ### beforeShowContainer

    protected void beforeShowContainer(Container c)

    This method allows binding an action that should occur before showing the given container

    ###### Parameters

    - `c`: the container about to be shown

  - ### postShowContainer

    protected void postShowContainer(Container c)

    This method allows binding an action that should occur immediately after showing the given container

    ###### Parameters

    - `c`: the container that was just shown

  - ### onCreateRoot

    protected void onCreateRoot(String rootName)

    This method allows binding logic that should occur before creating the root object e.g. a case where a created form needs data fetched for it.

    ###### Parameters

    - `rootName`: the name of the root to be created from the resource file

  - ### isKeepResourcesInRam

    public boolean isKeepResourcesInRam()

    Indicates that the UIBuilder should cache resources in memory and never release them. This is useful with small resource files or high RAM devices since it saves the cost of constantly fetching the res file from the jar whenever moving between forms. This can be toggled in the properties (e.g. jad) using the flag: cacheResFile (true/false) which defaults to false.

    ###### Returns

    the keepResourcesInRam

  - ### setKeepResourcesInRam

    public void setKeepResourcesInRam(boolean keepResourcesInRam)

    Indicates that the UIBuilder should cache resources in memory and never release them. This is useful with small resource files or high RAM devices since it saves the cost of constantly fetching the res file from the jar whenever moving between forms. This can be toggled in the properties (e.g. jad) using the flag: cacheResFile (true/false) which defaults to false.

    ###### Parameters

    - `keepResourcesInRam`: the keepResourcesInRam to set

  - ### getRootAncestor

    protected Container getRootAncestor(Component c)

    Returns either the parent form or the component below the embedded container above c.

    ###### Parameters

    - `c`: the component whose root ancestor we should find

    ###### Returns

    the root