org.peace_tools.generic.dndTabs
Class DnDTabPos

java.lang.Object
  org.peace_tools.generic.dndTabs.DnDTabPos

public class DnDTabPos
extends java.lang.Object

Class to remember position of a DnDTabPane. This class provides a reusable mechanism to remember the relative position of a DnDTabPane. This information is handy in the following cases:

• When hiding and showing windows, it is handy to restore tabs in the same location (as much as possible) where the user last placed it.
• The same concept can be applied to saving and resotring positions of windows in a persistent session file. Note that persisting to a session file is delegated to the actual application classes.

Field Summary

private java.util.ArrayList<DnDTabbedPane.Location>	path Vector to maintain path from center pane to the desired position of a tab.
(package private) javax.swing.Icon	prevIcon The icon (if any) to be used for the tab.
(package private) java.lang.String	prevName The name for the tab when its position is restored.
(package private) java.awt.Dimension	prevSize The preferred width / height of the tab.
(package private) boolean	visible An additional boolean to track if window is visible.

Constructor Summary

DnDTabPos()
The default constructor.

Method Summary

protected java.awt.Component	getPosition(java.awt.Component permTab, DnDTabbedPane.Location[] direction) Traverse saved position information as much as possible.
boolean	isVisible() Determine the visibility information in this tab.
void	restorePosition(java.awt.Container desktop, java.awt.Component tab) Primary interface to restore position of a tab.
private void	saveInfo(DnDTabbedPane owner, java.awt.Component tab) Helper method to save information about the given tab.
(package private) boolean	savePosition(java.awt.Component currWin, java.awt.Component tab) Recursive helper method to save relative position.
boolean	savePosition(java.awt.Container desktop, java.awt.Component tab) Method to save the relative position of a given child window.
void	setInfo(javax.swing.Icon icon, java.lang.String name, java.awt.Dimension size) Set initial information for restoring a window.
void	setVisible(boolean visible) Set the visibility information in this tab.

Methods inherited from class java.lang.Object

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

Field Detail

prevName

java.lang.String prevName

The name for the tab when its position is restored. This instance variable contains the name to be used for the tab when its position is restored. This information is updated in teh savePosition() method.

prevIcon

javax.swing.Icon prevIcon

The icon (if any) to be used for the tab. This instance variable contains a pointer to the icon to be used when restoring the tab. This pointer is updated in the savePosition() method.

prevSize

java.awt.Dimension prevSize

The preferred width / height of the tab. This instance variable is used to maintain the previous preferred width or height of the window. This information is updated in the savePosition() method. It is used only in the case that a new splitter window needs to be created when the tab is restored.

visible

boolean visible

An additional boolean to track if window is visible. This flag is used to track if the window associated with this DndTabPos object is currently visible or not. Note that this flag is really independent of the window's visibility. It is used by the application to operate on its own semantics which may be independent of wxWiget's semantics.

path

private java.util.ArrayList<DnDTabbedPane.Location> path

Vector to maintain path from center pane to the desired position of a tab. This vector is used to hold the necessary direction information that is used to remember the relative position of the given window with respect to the center pane. Entries in this vector are added by the savePosition() method and used by the restorePosition() methods.

Constructor Detail

DnDTabPos

public DnDTabPos()

The default constructor. The constructor has no special tasks to perform other than to initialize instance variables to their default initial value.

Method Detail

isVisible

public boolean isVisible()

Determine the visibility information in this tab. This method can be used to determine if the window (if any) logically associated with this object is visible or not.

Returns:

This method returns true if the window is visible. Otherwise it returns false.

setVisible

public void setVisible(boolean visible)

Set the visibility information in this tab. This method can be used to set if the window (if any) logically associated with this object is visible or not. Note that the visiblity flag is really independent of the window's visibility. It is used by the application to operate on its own semantics which may be independent of wxWiget's semantics.

Parameters:

visible - If this parameter is true then the window is assumed to be visible. Otherwise the window is assumed to be hidden.

setInfo

public void setInfo(javax.swing.Icon icon,
                    java.lang.String name,
                    java.awt.Dimension size)

Set initial information for restoring a window. This method can be used to initialize (or seed) this tab position helper with some information to restore a window.

Parameters:

icon - The icon to be used when restoring a window using this object.

name - The name of the tab to be used when restoring a window using this object.

size - The preferred size of the window when restoring.

savePosition

public boolean savePosition(java.awt.Container desktop,
                            java.awt.Component tab)

Method to save the relative position of a given child window. This method must be used to have this DndTabPos object to remember the relative position of a given child window. This method assumes that the child window is currently added to some DndTabPanel and is not orphaned (that is its parent pointer is still valid). Any previous position information stored in this class is lost.

Parameters:

desktop - The central desktop that contains all the panels including the permanent panel. The same panel should be used when restoring the window's position via the restorePosition() method.

tab - The tab (or child window) whose relative position must determined and remembered by this class.

Returns:

This method returns true if the relative position of this tab was successfully saved. If the relative position could not be saved, then this method returns false.

savePosition

boolean savePosition(java.awt.Component currWin,
                     java.awt.Component tab)

Recursive helper method to save relative position. This method is invoked from the overloaded savePosition() method with a suitable starting point. This method recursively calls itself until the DndTabPanel that contains the window whose location is to be remembered is reached. Once it finds the window, it saves the path traced as the recursion unwinds. Consequently, the path is saved in the reverse order of how the recursion proceeded.

Parameters:

currWin - The current window (may it be a DndTabPanel or a wxSplitWindow) from where the search for tab must proceed.

tab - The actual window that we are searching for.

Returns:

This method returns true if the position of the tab was found and the path was saved. Otherwise this method returns false.

saveInfo

private void saveInfo(DnDTabbedPane owner,
                      java.awt.Component tab)

Helper method to save information about the given tab. This is a helper method that is used to save information about a given child tab. The information saved includes the tab title text and the icon (if any) associated with the tab. This method updates the prevName and prevIcon instance variables.

Parameters:

owner - The owner tab panel from where the information about the child tab is to be saved.

tab - The child tab whose information is to be saved.

restorePosition

public void restorePosition(java.awt.Container desktop,
                            java.awt.Component tab)

Primary interface to restore position of a tab. This method is the complementary method to savePosition() method in this class. This method performs the task of repositioning a given tab within a DnDTabbedPane at its former position. This method does best effort to restore position of the tab. If the window layout has significantly changed, then this method places the window at at position at this closest to its pervious position without significantly impacting the current window layout.

Parameters:

desktop - The central desktop that contains all the panels including the permanent panel. The same panel should be used when saving the window's position via the savePosition() method.

tab - The component whose position is to be restored.

getPosition

protected java.awt.Component getPosition(java.awt.Component permTab,
                                         DnDTabbedPane.Location[] direction)

Traverse saved position information as much as possible. This is a helper method that was introduced to keep the code clutter in the restorePosition() to a minimum. This method does best effort to traverse the saved position information, while tracking the sequence of windows encountered.

Parameters:

permTab - The top-level permanent tab within which the position is to be determined.

direction - The last direction that was effectively traversed using the saved position information is set as the first element in this array. The caller must allocate this array to contain at least 1 element.

Returns:

The last window (split window or DndTabPanel as the case maybe) that was encountered during the traversal.