brf.j2me.dynaworks
Class Page

java.lang.Object
  |
  +--brf.j2me.dynaworks.Page

public abstract class Page

extends java.lang.Object

Abstract base class for application pages.

Page objects allows the application developer to use more then one screen page in an application. Each page has its own controls and event-handling.

User interface elements
GUI components can be added to a page by passing a reference to the component (derived from UserWidget) to the "add()" method. This is normally done in the constructor of the implementing class. The Page class then takes care of the control (repaint, event handling etc.) for all the controls added to it.

Event handling
A page receives a reference to an EventQueue instance that "feeds" the page with events. The page class handles or dispatches these events to the UserWidget controls or passes the directly to the 'handleEvent()' method in case they are posted 'ActionEvents'.

User interface elements emit events of type ActionEvent that are passed to the "handleEvent()" method of implementing classes. This is the place to code the interface logic of your page and to react to user interaction.

If you want to pass in an ActionEvent to the Page object from inside your application logic, you can use the "postEvent()" method to post an event for processing in the EventQueue. There can be any number of posted events at a time.

Application-wide data store
Pages have access to a application-wide data store that can be used to share data across pages. Data objects are stored in the dictionary by name; any Java object can be used as a data object in this object store. You can add, retrieve and remove data objects from the dictionary with the methods "addVariable()", "getVariable()" and "removeVariable()".

Linking to another page on exit
Every page is identified by a unique name. If the page "terminates" (e.g. the user pressed the "exit" button) it passes a String back to the Application object. This string tells the Application object what page to show next. The following rules apply to the String object:

1.) If the String is empty (or a "null" reference) than there is no request to load another page. The Application exits in case the call stack (see 2) is empty; otherwise the call stack is popped and the retrieved page is displayed.

2.) If the String starts with a '@' character, the name following that character are treated as the name of a page. This page is then loaded and the name of the "calling" page is pushed onto a call stack. This allows nested pages.

3.) If the String is a simple name, the corresponding page is loaded and activated (displayed)

To pass back this String reference, any implementing class must use the "exit()" method of the Page class to terminate processing; the name of the page (or the "null" reference) is passed into the "exit()" method as an argument.

Version:

1.0

Author:

Bernd R. Fix

See Also:

Application, UserWidget, DataDictionary, Event, EventQueue

Field Summary

protected static Audio	audio reference to physical audio.
protected static Graphics	canvas reference to physical screen.
protected java.util.Vector	comps list of docked components.
protected DataDictionary	data Reference to active data dictionary.
protected UserWidget	focus reference to widget that holds the focus.
protected java.lang.Object	modalLock
protected PopupWidget	modalWidget reference to popup widget.
protected java.lang.String	name name of the page.
protected java.lang.String	nextpage name of page to follow.
protected EventQueue	queue reference to event queue.
protected boolean	running Is the task active?

Constructor Summary

Page(java.lang.String name)
constructor.

Method Summary

(package private) static void	() static initialization of class.
boolean	add(UserWidget comp) add a user interface element.
protected boolean	addVariable(java.lang.String key, java.lang.Object value) add a data object to the dictionary.
void	dispatchEvent(Event e) Dispatch events: ActionEvents are passed directly to the 'handleEvent()' method of the implementing class whereas 'normal' events are actually dispatched to the user widgets.
void	exit(java.lang.String nextpage) leave the page.
java.lang.String	getName() get the name of the page.
protected java.lang.Object	getVariable(java.lang.String name) retrieve a data object from the dictionary.
abstract boolean	handleEvent(ActionEvent e) handle events from user interface elements.
void	keyDown(int keyCode) The user has entered a keystroke.
void	paint() All user interface elements have to be repainted.
void	penDown(int x, int y) User touches the canvas at the given coordinates.
void	penMove(int x, int y) User moves on the canvas to the given coordinates.
void	penUp(int x, int y) User lifts pen from the canvas at the given coordinates.
java.lang.String	perform(EventQueue queue, boolean clear) this is the page entry point.
protected boolean	postEvent(Event e) Post an Event.
protected boolean	removeVariable(java.lang.String name) remove a data object.
int	run(PopupWidget comp) running a modal popup widget.
DataDictionary	setData(DataDictionary data) assign the data store.
void	sysKeyDown(int keyCode) The user has pressed a system key.

Methods inherited from class java.lang.Object

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

Field Detail

name

protected java.lang.String name

name of the page.

canvas

protected static Graphics canvas

reference to physical screen.

audio

protected static Audio audio

reference to physical audio.

modalWidget

protected PopupWidget modalWidget

reference to popup widget.

modalLock

protected java.lang.Object modalLock

running

protected boolean running

Is the task active?

focus

protected UserWidget focus

reference to widget that holds the focus.

queue

protected EventQueue queue

reference to event queue.

data

protected DataDictionary data

Reference to active data dictionary.

comps

protected java.util.Vector comps

list of docked components.

nextpage

protected java.lang.String nextpage

name of page to follow.

Constructor Detail

Page

public Page(java.lang.String name)

constructor.

Parameters:

name - String - name of the page.

Method Detail

static void ()

static initialization of class.

See Also:

Graphics, Audio

setData

public DataDictionary setData(DataDictionary data)

assign the data store.

This method is usually called by the Application object when a page is added to the application. It sets the application specific data dictionary that can be used by pages of one application to share information.

Parameters:

data - DataDictionary - data store for application variables.

Returns:

DataDictionary - last object store that was assigned.

See Also:

DataDictionary

getVariable

protected java.lang.Object getVariable(java.lang.String name)

retrieve a data object from the dictionary.

Parameters:

name - String - name of the variable.

Returns:

Object - matching data object (or null)

See Also:

DataDictionary, addVariable(java.lang.String, java.lang.Object), removeVariable(java.lang.String)

addVariable

protected boolean addVariable(java.lang.String key,
                              java.lang.Object value)

add a data object to the dictionary.

Parameters:

key - String - name of the variable.

value - Object - data object

Returns:

boolean - success of operation.

See Also:

DataDictionary, getVariable(java.lang.String), removeVariable(java.lang.String)

removeVariable

protected boolean removeVariable(java.lang.String name)

remove a data object.

Parameters:

name - String - name of the variable.

Returns:

boolean - success of operation.

See Also:

DataDictionary, getVariable(java.lang.String), addVariable(java.lang.String, java.lang.Object)

handleEvent

public abstract boolean handleEvent(ActionEvent e)

handle events from user interface elements.

Parameters:

e - ActionEvent - event passed to system.

See Also:

ActionEvent, postEvent(brf.j2me.dynaworks.env.Event)

postEvent

protected boolean postEvent(Event e)

Post an Event.

Parameters:

e - Event - event to be posted.

Returns:

boolean - event posted?

See Also:

Event, EventQueue, handleEvent(brf.j2me.dynaworks.ActionEvent)

dispatchEvent

public void dispatchEvent(Event e)

Dispatch events: ActionEvents are passed directly to the 'handleEvent()' method of the implementing class whereas 'normal' events are actually dispatched to the user widgets.

Parameters:

e - Event - event to be dispatched.

See Also:

ActionEvent, Event, EventQueue

perform

public java.lang.String perform(EventQueue queue,
                                boolean clear)

this is the page entry point.

Parameters:

clear - boolean - clear the screen.

Returns:

String - name of the page that is to be run next. An NULL reference or an empty string by default mean "page exit". A string of the form "" forces an application exit.

exit

public void exit(java.lang.String nextpage)

leave the page.

Parameters:

nextpage - String - name of the next page to be loaded.

run

public int run(PopupWidget comp)

running a modal popup widget.

Parameters:

comp - PopupWidget - user interface control to be displayed.

Returns:

int - result code of popup.

See Also:

PopupWidget

add

public boolean add(UserWidget comp)

add a user interface element.

Parameters:

comp - UserWidget - user interface control to be added.

Returns:

boolean - adding successful?

See Also:

UserWidget

getName

public java.lang.String getName()

get the name of the page.

Returns:

String - name of the page.

paint

public void paint()

All user interface elements have to be repainted.

penDown

public void penDown(int x,
                    int y)

User touches the canvas at the given coordinates.

Parameters:

x - int - coordinate

y - int - coordinate

penMove

public void penMove(int x,
                    int y)

User moves on the canvas to the given coordinates.

Parameters:

x - int - coordinate

y - int - coordinate

penUp

public void penUp(int x,
                  int y)

User lifts pen from the canvas at the given coordinates.

Parameters:

x - int - coordinate

y - int - coordinate

keyDown

public void keyDown(int keyCode)

The user has entered a keystroke.

Parameters:

keyCode - int - keystroke entered.

sysKeyDown

public void sysKeyDown(int keyCode)

The user has pressed a system key.

Parameters:

keyCode - int - key pressed.