com.sun.lwuit.util
Class UIBuilder

java.lang.Object
  com.sun.lwuit.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.sun.lwuit package (even a Component from sub packages such as table or tree) it MUST be registered before loading a GUI!

Field Summary

static int	BACK_COMMAND_ID
static java.lang.String	FORM_STATE_KEY_FOCUS A key in the form state hashtable used in the back command navigation
static java.lang.String	FORM_STATE_KEY_NAME A key in the form state hashtable used in the back command navigation
static java.lang.String	FORM_STATE_KEY_SELECTION A key in the form state hashtable used in the back command navigation

Constructor Summary

UIBuilder()

Method Summary

void	addCommandListener(ActionListener l) Adds a command listener that would be bound to all forms in the GUI seamlessly
void	addCommandListener(java.lang.String formName, ActionListener l) Adds a command listener to be invoked for commands on a specific form
void	addComponentListener(java.lang.String formName, java.lang.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(java.lang.String formName) Indicates whether a back command to this form should be generated automatically when leaving said form.
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 LWUIT 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.
protected Command	createCommand(java.lang.String commandName, Image icon, int commandId, java.lang.String action) Creates a command instance.
protected Component	createComponentInstance(java.lang.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, java.lang.String resourceName) Creates the container defined under the given name in the res file
Container	createContainer(java.lang.String resPath, java.lang.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. memory cleanup
protected Resources	fetchResourceFile() This method may be overriden by subclasses to provide a way to dynamically load a resource file.
Component	findByName(java.lang.String name, Container rootComponent) Finds the given component by its name
protected java.util.Hashtable	getContainerState(Container cnt) This method is the container navigation equivalent of getFormState() see that method for details.
protected java.util.Hashtable	getFormState(Form f) Returns the state of the current form which we are about to leave as part of the navigation logic.
java.lang.String	getHomeForm() When reaching the home form the navigation stack is cleared
java.lang.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 bellow 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
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	onCreateRoot(java.lang.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.
protected void	postAsyncCommand(Command cmd, ActionEvent sourceEvent) This method is invoked in conjunction with asyncCommandProcess after the command was handled asynchroniously 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(java.lang.String name, java.lang.Class cmp) This method allows the UIBuilder to package a smaller portion of LWUIT 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(java.lang.String formName, ActionListener l) Removes a command listener on a specific form
void	removeComponentListener(java.lang.String formName, java.lang.String componentName, java.lang.Object listener) Removes a component listener bound to a specific component
void	setBackCommandEnabled(boolean back) Seamlessly inserts a back command to all the forms
protected void	setContainerState(Container cnt, java.util.Hashtable state) This method is the container navigation equivalent of setFormState() see that method for details.
protected void	setFormState(Form f, java.util.Hashtable state) Sets the state of the current form to which we are returing as part of the navigation logic.
void	setHomeForm(java.lang.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 void	setResourceFile(Resources res) Sets the resource file if keep in rum or no path is defined
void	setResourceFilePath(java.lang.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
Container	showContainer(java.lang.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(java.lang.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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORM_STATE_KEY_NAME

public static final java.lang.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_FOCUS

public static final java.lang.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 java.lang.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 Detail

UIBuilder

public UIBuilder()

Method Detail

setBackCommandEnabled

public void setBackCommandEnabled(boolean back)

Seamlessly inserts a back command to all the forms

Parameters:

back - true to automatically add a back command

isBackCommandEnabled

public boolean isBackCommandEnabled()

Seamlessly inserts a back command to all the forms

Returns:

true if a back command is automatically added

registerCustomComponent

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

This method allows the UIBuilder to package a smaller portion of LWUIT 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.sun.lwuit is registered however subpackages and 3rd party components are not. Registeration is essential for obfuscation to work properly!

Parameters:

name - the name of the component (UIID)

cmp - the class for the given component

createContainer

public Container createContainer(java.lang.String resPath,
                                 java.lang.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 LWUIT container instance

createContainer

public Container createContainer(Resources res,
                                 java.lang.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 LWUIT container instance

findByName

public Component findByName(java.lang.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(java.lang.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 LWUIT 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 LWUIT 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

createCommand

protected Command createCommand(java.lang.String commandName,
                                Image icon,
                                int commandId,
                                java.lang.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 java.lang.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(java.lang.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(java.lang.String formName,
                                 java.lang.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(java.lang.String formName,
                                    java.lang.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(java.lang.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(java.lang.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 overide 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 asynchroniously on the separate thread. Here LWUIT 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 - 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:

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

getFormState

protected java.util.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

setFormState

protected void setFormState(Form f,
                            java.util.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 java.util.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,
                                 java.util.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 java.lang.String getHomeForm()

When reaching the home form the navigation stack is cleared

Returns:

the homeForm

setHomeForm

public void setHomeForm(java.lang.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 - 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.

showContainer

public Container showContainer(java.lang.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:

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

allowBackTo

protected boolean allowBackTo(java.lang.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:

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(java.lang.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:

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

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(java.lang.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 bellow the embedded container above c.

Parameters:

c - the component whose root ancestor we should find

Returns:

the root