com.yospace.yae.pm
Class PaneletManager

java.lang.Object
  |
  +--com.yospace.yae.pm.PaneletManager

Direct Known Subclasses:

SimplePaneletManager, SinglePaneletManager

public abstract class PaneletManager

extends java.lang.Object

The Panelet manager is responsible for the current collection of Panelets. It maintains an ordered list of Panelets, accessible by index, where the zeroth element is the least recently touched. (Note that the index of a given panelet may change at any time, so full synchronization is necessary).

Field Summary

protected ApplicationManager	appMan A back-reference to the Application Manager.
static int	PROPERTY_ACTIVE The constant defining the property of a Panelet being active.
static int	PROPERTY_ADDED The constant defining the property of a Panelet being added.
static int	PROPERTY_PANELET_STATE The constant defining the property of a Panelet's state.
static int	PROPERTY_REMOVED The constant defining the property of a Panelet being removed.

Constructor Summary

protected

PaneletManager() Simply sets up an empty Vector of current Panelets.

Method Summary

void	add(Panelet p) Adds a Panelet to the end of the current set of Panelets.
void	addPropertyChangeListener(PropertyChangeListener newPcl) Adds a listener for any of the various property change events that components can produce.
abstract void	exit() Abstract method which, when implemented, should be used to tell the system to exit.
void	firePropertyChangeEvent(int propertyCode) This method is used to send a notification to any registered PropertyChangeListeners to say that the specified property has changed.
void	firePropertyChangeEvent(java.lang.Object source, int propertyCode) This method is used to send a notification to any registered PropertyChangeListeners to say that the specified property has changed.
Panelet	getActivePanelet() Gets the currently active Panelet.
Panelet	getPanelet(int index) Returns the Panelet at the specified index.
Panelet	getPanelet(YogiComponent child) Finds the Panelet to which the specified child belongs.
PaneletConfigBuilder	getPaneletConfig() Gets the mappings of Panelet names to their associated class, XML and resource files, as declared in the Panelet config XML file.
int	getPaneletCount() Returns the number of registered Panelets.
void	init(PaneletConfigBuilder paneletConfig, ApplicationManager appMan, YogiComponent popupComponentParent) Initialises the Panelet Manager.
void	remove(Panelet p) Removes the specified Panelet from the current set.
void	removePropertyChangeListener(PropertyChangeListener oldPcl) This method removes a PropertyChangeListener that may have been registered previously.
void	setActivePanelet(int i) Sets the currently active Panelet to be that with the given index.
abstract void	setPaneletState(Panelet thePanelet, int newState) It is expected that all subclasses of this abstract base class implement this method, which handles a request to change the state of a Panelet.
abstract void	start() Called by YaeMIDlet to start up this manager.
void	startPanelet(java.lang.String name) Generates and starts a Panelet by getting the relevant application parameters.
protected void	touch(Panelet p) Moves the specified Panelet to the end of the set.
protected void	updatePaneletState(Panelet thePanelet, int newState) Used internally to modify a Panelets state to the given new state.

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTY_ADDED

public static final int PROPERTY_ADDED

The constant defining the property of a Panelet being added.

PROPERTY_REMOVED

public static final int PROPERTY_REMOVED

The constant defining the property of a Panelet being removed.

PROPERTY_PANELET_STATE

public static final int PROPERTY_PANELET_STATE

The constant defining the property of a Panelet's state.

PROPERTY_ACTIVE

public static final int PROPERTY_ACTIVE

The constant defining the property of a Panelet being active.

appMan

protected ApplicationManager appMan

A back-reference to the Application Manager.

Constructor Detail

PaneletManager

protected PaneletManager()

Simply sets up an empty Vector of current Panelets.

Method Detail

init

public void init(PaneletConfigBuilder paneletConfig,
                 ApplicationManager appMan,
                 YogiComponent popupComponentParent)

Initialises the Panelet Manager. Sets the Application Manager that this Panelet Manager is associated with, and also the Panelet Configuration file to be used. Can only be set once (which should be by the Application Manager itself when initially setting-up the Panelet Manager).

Parameters:

paneletConfig - the Panelet Configuration for this YoGI session.

appMan - the Application Manager to be associated with this Panelet Manager.

popupComponentParent - the component parent to use when a Dialog is required. This will be the case when the request to start a Panelet fails.

Throws:

IllegalStateException - if the Application Manager has already been set up.

start

public abstract void start()

Called by YaeMIDlet to start up this manager.

startPanelet

public void startPanelet(java.lang.String name)

Generates and starts a Panelet by getting the relevant application parameters. Creates a new Panelet and then generates the UI associated with that Panelet through the XML UI building framework.

Parameters:

name - the Panelet name (as used in the Panelet Config) to start.

add

public void add(Panelet p)

Adds a Panelet to the end of the current set of Panelets. If already present, the method does nothing. A property change event is fired once the Panelet has been added, and it is expected that the Dashboard catches this event and updates the view accordingly.

Parameters:

p - the panelet to add.

remove

public void remove(Panelet p)

Removes the specified Panelet from the current set. All Panelet indices above are moved down to fill the gap. If the Panelet is not in the set, then the method does nothing. A property change event is fired once the Panelet has been removed, and it is expected that the Dashboard catches this event and updates the view accordingly.

Parameters:

p - the Panelet to be removed.

getPanelet

public Panelet getPanelet(int index)

Returns the Panelet at the specified index.

Parameters:

index - the index of the Panelet to be retrieved.

Returns:

the Panelet at the index.

Throws:

ArrayIndexOutOfBoundsException - if the index lies outside the range 0 <= index < number of panelets

getPanelet

public Panelet getPanelet(YogiComponent child)

Finds the Panelet to which the specified child belongs.

Parameters:

child - the component whose Panelet is required

Returns:

the parent Panelet

getPaneletCount

public int getPaneletCount()

Returns the number of registered Panelets.

Returns:

the number of registered Panelets

getPaneletConfig

public PaneletConfigBuilder getPaneletConfig()

Gets the mappings of Panelet names to their associated class, XML and resource files, as declared in the Panelet config XML file.

Returns:

the Panelet config.

setActivePanelet

public void setActivePanelet(int i)

Sets the currently active Panelet to be that with the given index.

Parameters:

i - the index of the Panelet in this manager's list to set as active.

getActivePanelet

public Panelet getActivePanelet()

Gets the currently active Panelet.

Returns:

the currently active Panelet.

touch

protected void touch(Panelet p)

Moves the specified Panelet to the end of the set. This is equivalent to a "remove" followed by an "add". It has the effect of making the Panelet act as though it is the most recently added Panelet. If the Panelet is not in the set, then it is added anyway.

Parameters:

p - the panelet to be moved.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener newPcl)

Adds a listener for any of the various property change events that components can produce. A component does not guarantee the order in which listeners are notified. If it is absolutely necessary that a particular order be maintained, then the two listeners are not independent, and thus the first listener should probably be alerting the second.

Parameters:

newPcl - the property change listener to be added. If it is already a listener, then this method does nothing.

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener oldPcl)

This method removes a PropertyChangeListener that may have been registered previously. If no such listener was registered, then this method does nothing.

Parameters:

oldPcl - the listener to be removed.

firePropertyChangeEvent

public void firePropertyChangeEvent(int propertyCode)

This method is used to send a notification to any registered PropertyChangeListeners to say that the specified property has changed.

Parameters:

propertyCode - the property that has changed. For maximum efficiency, this should be one of the PROPERTY_XXXXX constants.

firePropertyChangeEvent

public void firePropertyChangeEvent(java.lang.Object source,
                                    int propertyCode)

This method is used to send a notification to any registered PropertyChangeListeners to say that the specified property has changed.

Parameters:

source - the source from which this event purports to be fired from.

propertyCode - the property that has changed. For maximum efficiency, this should be one of the PROPERTY_XXXXX constants.

setPaneletState

public abstract void setPaneletState(Panelet thePanelet,
                                     int newState)

It is expected that all subclasses of this abstract base class implement this method, which handles a request to change the state of a Panelet.

Parameters:

thePanelet - the Panelet whose state is to be set.

newState - the target state for the given Panelet.

updatePaneletState

protected void updatePaneletState(Panelet thePanelet,
                                  int newState)

Used internally to modify a Panelets state to the given new state. Fires a property change event upon completion.

Parameters:

thePanelet - the Panelet whose state needs changing.

newState - the new state for the Panelet.

exit

public abstract void exit()

Abstract method which, when implemented, should be used to tell the system to exit.