com.jidesoft.dashboard
Class GadgetManager

java.lang.Object
  com.jidesoft.dashboard.GadgetManager

public class GadgetManager
extends Object

You can view GadgetManager as the model of the whole JIDE Dashboard. It has a list of dashboards and gadgets.

Any DashboardHolder must work with a GadgetManager. It should also listen to GadgetEvents or DashboardEvents fired by GadgetManager to update the UI.

If you want to add or remove gadgets or dashboards, you should do it through methods provided by GadgetManager.

Field Summary

protected EventListenerList

listenerList A list of event listeners for this component.

Constructor Summary

GadgetManager()
Creates an empty GadgetManager.

Method Summary

void	addDashboard(Dashboard dashboard) Adds a new dashboard.
void	addDashboardListener(DashboardListener l) Adds the specified listener to receive dashboard events from this dashboard.
void	addGadget(Gadget gadget) Adds a new gadget.
void	addGadget(Gadget gadget, int index) Adds a new gadget at the specified index.
void	addGadgetListener(GadgetListener l) Adds the specified listener to receive gadget events from this gadget.
GadgetComponent	createGadgetComponent(Gadget gadget) Creates a gadget component.
protected void	fireDashboardEvent(DashboardEvent e) Fires a dashboard event.
protected void	fireGadgetEvent(GadgetEvent e) Fires a gadget event.
String	getActiveDashboardKey() Gets the active Dashboard key.
KeyListener	getCancelDragAndDropKeyListener() Gets the key listener.
Dashboard	getDashboard(int index) Gets the dashboard at the specified index.
Dashboard	getDashboard(String key) Gets the dashboard by the key.
int	getDashboardCount() Gets the number of dashboards.
int	getDashboardIndex(String key) Gets the dashboard index.
DashboardListener[]	getDashboardListeners() Returns an array of all the DashboardListeners added to this DashboardGroup with addDashboardListener.
String[]	getDashboards() Gets all the dashboards.
MouseInputListener	getDragAndDropMouseInputListener() Gets the mouse input listener needed to support drag-n-drop feature of the gadget component.
Gadget	getGadget(String key) Gets the gadget by the key.
GadgetListener[]	getGadgetListeners() Returns an array of all the GadgetListeners added to this GadgetGroup with addGadgetListener.
String[]	getGadgets() Gets all the gadgets added to be this GadgetManager.
String	getVersion() Gets an optional version string.
void	hideGadget(GadgetComponent gadgetComponent) Hides the GadgetComponent.
protected void	initManager() Initializes the manager.
void	installListeners(Component component) Installs getDragAndDropMouseInputListener and getCancelDragAndDropKeyListener to the components.
boolean	isAllowDragBetweenDashboard() Get the flag indicating if the gadget is allowed to be dropped from one dashboard to another.
boolean	isAllowDragOutside() Get the flag indicating if the gadget is allowed to be dropped in the closest location upon dragged outside of the Dashboard.
boolean	isAllowMultipleGadgetInstances() Get the flag indicating if the gadget manager allows multiple gadget instances.
boolean	isColumnResizable() Get the flag indicating if the column is resizable.
boolean	isDisposeGadgetsWhenHidingDashboard() Checks the flag whether the gadgets will be disposed when the dashborad is hidden.
boolean	isGadgetShown(Gadget gadget) Check if a gadget is displayed already.
boolean	isGadgetShown(String key) Check if a gadget is displayed already.
void	maximizeGadget(GadgetComponent component) Maximize the designated GadgetComponent.
void	maximizeGadget(int column, int row) Maximize the GadgetComponent in designated column and row in the active dashboard.
void	moveDashboard(String key, int index) Moves an existing dashboard.
void	removeAllDashboards() Removes all the dashboards.
boolean	removeDashboard(String key) Removes a dashboard.
void	removeDashboardListener(DashboardListener l) Removes the specified dashboard listener so that it no longer receives dashboard events.
boolean	removeGadget(String key) Removes an existing gadget.
void	removeGadgetListener(GadgetListener l) Removes the specified gadget listener so that it no longer receives gadget events.
void	restoreGadget() Restore the maximized GadgetComponent in the active dashboard.
void	setActiveDashboardKey(String key) Sets the active Dashboard by the key.
void	setAllowDragBetweenDashboard(boolean allowDragBetweenDashboard) Set the flag indicating if the gadget is allowed to be dropped from one dashboard to another.
void	setAllowDragOutside(boolean allowDragOutside) Set the flag indicating if the gadget is allowed to be dropped in the closest location upon dragged outside of the Dashboard.
void	setAllowMultipleGadgetInstances(boolean allowMultipleGadgetInstances) Set the flag indicating if the gadget manager allows multiple gadget instances.
void	setColumnResizable(boolean columnResizable) Set the flag indicating if the column is resizable.
void	setDisposeGadgetsWhenHidingDashboard(boolean disposeGadgetsWhenHidingDashboard) Sets the flag whether the gadgets will be disposed when the dashborad is hidden.
void	setVersion(String version) Sets version string.
void	showGadget(Gadget gadget) Shows a gadget.
void	showGadget(Gadget gadget, Dashboard dashboard, int column, int index) Shows a gadget.
void	uninstallListeners(Component component) Uninstalls getDragAndDropMouseInputListener and getCancelDragAndDropKeyListener from the components.
protected boolean	validateGadgetDragging(Gadget gadget, Container targetContainer) A validation method before gadget is dropped to a target container.

Methods inherited from class java.lang.Object

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

Field Detail

listenerList

protected EventListenerList listenerList

A list of event listeners for this component.

Constructor Detail

GadgetManager

public GadgetManager()

Creates an empty GadgetManager.

Method Detail

initManager

protected void initManager()

Initializes the manager.

addGadget

public void addGadget(Gadget gadget,
                      int index)

Adds a new gadget at the specified index.

Parameters:

gadget - a new gadget to be added.

index - the gadget index.

addGadget

public void addGadget(Gadget gadget)

Adds a new gadget.

Parameters:

gadget - a new gadget to be added.

removeGadget

public boolean removeGadget(String key)

Removes an existing gadget.

Parameters:

key - the key of the gadget to be removed.

Returns:

true if removed successfully. Otherwise false.

showGadget

public void showGadget(Gadget gadget)

Shows a gadget. This method will create a GadgetComponent from the specified Gadget and show it at the first position in the active dashboard.

Parameters:

gadget - the Gadget to be shown.

showGadget

public void showGadget(Gadget gadget,
                       Dashboard dashboard,
                       int column,
                       int index)

Shows a gadget. This method will create a GadgetComponent from the specified Gadget and show it at the designated position in the designated dashboard.

Parameters:

gadget - the Gadget to be shown

dashboard - the dashboard to display the gadget

column - the column in the dashboard to display the gadget. If the column is bigger than the column count of the dashboard, nothing will display

index - the index in the column to display the gadget. If the index is invalid, we will just add it to the last available position

isGadgetShown

public boolean isGadgetShown(String key)

Check if a gadget is displayed already.

Parameters:

key - the key of the gadget

Returns:

true if the gadget is displayed already. Otherwise false.

isGadgetShown

public boolean isGadgetShown(Gadget gadget)

Check if a gadget is displayed already.

Parameters:

gadget - the gadget

Returns:

true if the gadget is displayed already. Otherwise false.

hideGadget

public void hideGadget(GadgetComponent gadgetComponent)

Hides the GadgetComponent.

Parameters:

gadgetComponent - the GadgetComponent to be hidden.

maximizeGadget

public void maximizeGadget(GadgetComponent component)

Maximize the designated GadgetComponent. It will do nothing if the GadgetComponent does not exist in normal gadget container in its active dashboard.

Parameters:

component - the gadget component

maximizeGadget

public void maximizeGadget(int column,
                           int row)

Maximize the GadgetComponent in designated column and row in the active dashboard. It will do nothing if the parameter is invalid.

Parameters:

column - the column index

row - the row index

restoreGadget

public void restoreGadget()

Restore the maximized GadgetComponent in the active dashboard.

createGadgetComponent

public GadgetComponent createGadgetComponent(Gadget gadget)

Creates a gadget component. This method will create a GadgetComponent from the specified Gadget and return it.

Parameters:

gadget - the Gadget to be shown.

Returns:

the GadgetComponent created from the gadget. Null if the Gadget doesn't belong to this GadgetManager or Gadget returns null in its createGadgetComponent method.

getActiveDashboardKey

public String getActiveDashboardKey()

Gets the active Dashboard key.

Returns:

the active Dashboard key.

setActiveDashboardKey

public void setActiveDashboardKey(String key)

Sets the active Dashboard by the key. This method will fire DashboardEvent.DASHBOARD_DEACTIVATED on the previous active dashboard and fire DashboardEvent.DASHBOARD_ACTIVATED on the newly activated dashboard. However it is up to the DashboardHolder to listen to this event and active the corresponding dashboard (for example, we did that in DashboardTabbedPane), or ignore it if there is only one dashboard (such as SingleDashboardHolder)..

Parameters:

key - the key of the Dashboard to be activated.

getGadget

public Gadget getGadget(String key)

Gets the gadget by the key.

Parameters:

key - the key of the gadget.

Returns:

the gadget or null if not found.

getGadgets

public String[] getGadgets()

Gets all the gadgets added to be this GadgetManager.

Returns:

all the gadgets.

addDashboard

public void addDashboard(Dashboard dashboard)

Adds a new dashboard.

Parameters:

dashboard - the dashboard to be added.

removeDashboard

public boolean removeDashboard(String key)

Removes a dashboard.

Parameters:

key - the key of the dashboard to be removed.

Returns:

true if removed successfully. Otherwise false.

moveDashboard

public void moveDashboard(String key,
                          int index)

Moves an existing dashboard.

Parameters:

key - the key of the dashboard to be moved.

index - the new index.

removeAllDashboards

public void removeAllDashboards()

Removes all the dashboards.

getDashboard

public Dashboard getDashboard(String key)

Gets the dashboard by the key.

Parameters:

key - the key of the dashboard.

Returns:

the dashboard or null if not found.

getDashboardIndex

public int getDashboardIndex(String key)

Gets the dashboard index.

Parameters:

key - the key of the dashboard.

Returns:

the index of the dashboard. -1 if not found.

getDashboard

public Dashboard getDashboard(int index)

Gets the dashboard at the specified index.

Parameters:

index - the index

Returns:

the dashboard at the index.

getDashboards

public String[] getDashboards()

Gets all the dashboards.

Returns:

all the dashboards.

getDashboardCount

public int getDashboardCount()

Gets the number of dashboards.

Returns:

the number of dashboards.

validateGadgetDragging

protected boolean validateGadgetDragging(Gadget gadget,
                                         Container targetContainer)

A validation method before gadget is dropped to a target container. By default, it will return true. You could override this method to add some widgets or checking here.

Parameters:

gadget - the dragging gadget

targetContainer - the target container

Returns:

true if dragging is allowed. Otherwise false.

getDragAndDropMouseInputListener

public MouseInputListener getDragAndDropMouseInputListener()

Gets the mouse input listener needed to support drag-n-drop feature of the gadget component. In most cases, you will never need to call this as the listener will be added to all gadget components created by GadgetPalette. But if for whatever reason you have to create the gadget component yourself or your component has a child component that also needs to support drag-n-drop, you can get this listener and add it yourself. Of course you can also call installListeners(java.awt.Component) which will get the listener and add it.

Returns:

the mouse input listener needed to support drag-n-drop feature of the gadget component.

getCancelDragAndDropKeyListener

public KeyListener getCancelDragAndDropKeyListener()

Gets the key listener. During any drag-n-drop, this key listener will response to ESCAPE to cancel the operation. Same as getDragAndDropMouseInputListener, this key listener is added to the necessary component by default if the drag-n-drop is starting from the palette. But if you are starting any drag-n-drop from your code, you can add this listener to the component which will receive key event during the drag-n-drop.

Returns:

the key listener which will response to ESCAPE key and stop the drag-n-drop operation.

installListeners

public void installListeners(Component component)

Installs getDragAndDropMouseInputListener and getCancelDragAndDropKeyListener to the components.

Parameters:

component - the component where two listeners will be added.

uninstallListeners

public void uninstallListeners(Component component)

Uninstalls getDragAndDropMouseInputListener and getCancelDragAndDropKeyListener from the components.

Parameters:

component - the component where two listeners were added.

addGadgetListener

public void addGadgetListener(GadgetListener l)

Adds the specified listener to receive gadget events from this gadget.

Parameters:

l - the gadget listener

removeGadgetListener

public void removeGadgetListener(GadgetListener l)

Removes the specified gadget listener so that it no longer receives gadget events.

Parameters:

l - the gadget listener

getGadgetListeners

public GadgetListener[] getGadgetListeners()

Returns an array of all the GadgetListeners added to this GadgetGroup with addGadgetListener.

Returns:

all of the GadgetListeners added or an empty array if no listeners have been added

See Also:

addGadgetListener(com.jidesoft.dashboard.GadgetListener)

fireGadgetEvent

protected void fireGadgetEvent(GadgetEvent e)

Fires a gadget event.

Parameters:

e - the event

addDashboardListener

public void addDashboardListener(DashboardListener l)

Adds the specified listener to receive dashboard events from this dashboard.

Parameters:

l - the dashboard listener

removeDashboardListener

public void removeDashboardListener(DashboardListener l)

Removes the specified dashboard listener so that it no longer receives dashboard events.

Parameters:

l - the dashboard listener

getDashboardListeners

public DashboardListener[] getDashboardListeners()

Returns an array of all the DashboardListeners added to this DashboardGroup with addDashboardListener.

Returns:

all of the DashboardListeners added or an empty array if no listeners have been added

See Also:

addDashboardListener(com.jidesoft.dashboard.DashboardListener)

fireDashboardEvent

protected void fireDashboardEvent(DashboardEvent e)

Fires a dashboard event.

Parameters:

e - the event

getVersion

public String getVersion()

Gets an optional version string.

Returns:

version string.

setVersion

public void setVersion(String version)

Sets version string.

Parameters:

version - the new version

isDisposeGadgetsWhenHidingDashboard

public boolean isDisposeGadgetsWhenHidingDashboard()

Checks the flag whether the gadgets will be disposed when the dashborad is hidden.

Returns:

true or false.

setDisposeGadgetsWhenHidingDashboard

public void setDisposeGadgetsWhenHidingDashboard(boolean disposeGadgetsWhenHidingDashboard)

Sets the flag whether the gadgets will be disposed when the dashborad is hidden. Default is true. But when you load the layout, this flag should be tempararily set to false. Here is the right way to load the layout.

 DashboardPersistenceUtils.load(_documentPane, the layout file saved by DashboardPersistenceUtils);
 try {
     _documentPane.getGadgetManager().setDisposeGadgetsWhenHidingDashboard(false);
     _documentPane.getLayoutPersistence().loadLayoutData();
 }
 finally {
     _documentPane.getGadgetManager().setDisposeGadgetsWhenHidingDashboard(true);
 }
 

Parameters:

disposeGadgetsWhenHidingDashboard - true or false.

isColumnResizable

public boolean isColumnResizable()

Get the flag indicating if the column is resizable.

The default value of this flag is false to keep consistent behavior with earlier release.

Returns:

the flag

setColumnResizable

public void setColumnResizable(boolean columnResizable)

Set the flag indicating if the column is resizable.

Parameters:

columnResizable - the flag

isAllowDragOutside

public boolean isAllowDragOutside()

Get the flag indicating if the gadget is allowed to be dropped in the closest location upon dragged outside of the Dashboard.

The default value is true to keep the original behavior.

Returns:

the flag.

setAllowDragOutside

public void setAllowDragOutside(boolean allowDragOutside)

Set the flag indicating if the gadget is allowed to be dropped in the closest location upon dragged outside of the Dashboard.

Parameters:

allowDragOutside - the flag

isAllowDragBetweenDashboard

public boolean isAllowDragBetweenDashboard()

Get the flag indicating if the gadget is allowed to be dropped from one dashboard to another.

By default the value is true.

Returns:

true if allow dragging between dashboard. Otherwise false.

setAllowDragBetweenDashboard

public void setAllowDragBetweenDashboard(boolean allowDragBetweenDashboard)

Set the flag indicating if the gadget is allowed to be dropped from one dashboard to another.

Parameters:

allowDragBetweenDashboard - the flag

See Also:

isAllowDragBetweenDashboard()

isAllowMultipleGadgetInstances

public boolean isAllowMultipleGadgetInstances()

Get the flag indicating if the gadget manager allows multiple gadget instances.

The default value is true, which means you can drag the button to create as many gadget components as you want. You could set it to false if you want only one gadget component to be created for one gadget.

Returns:

true if multiple gadget instances are allowed. Otherwise false.

setAllowMultipleGadgetInstances

public void setAllowMultipleGadgetInstances(boolean allowMultipleGadgetInstances)

Set the flag indicating if the gadget manager allows multiple gadget instances.

Parameters:

allowMultipleGadgetInstances - the flag

See Also:

isAllowMultipleGadgetInstances()