org.flexdock.util
Class NestedComponents

java.lang.Object
  extended by org.flexdock.util.NestedComponents

public class NestedComponents
extends Object

This is a utility class for small, short-lived object instances used to find nested Components. It models a relationship between nested Components within an AWT Container hierarchy such that, given a starting Component from which to search, it will find two Components nested within each other of specific class types. The "deeper" component will be a descendent of the "parent" component.

For example, given a JTextField within a content frame, the application logic may need to check to see if the text field resides within a certain application-specific container set. Perhaps all JTables embedded within JSplitPanes are significant within the particular application. The find(Component searchSrc, Class childClass, Class parentClass) method on this class will be able to return a NestedComponents instance indicating whether the specified text field resides within a JTable that is embedded within a JSplitPane.

Although perhaps a bit contrived, this example shows a generic use for this class. The FlexDock framework itself has a particular interest in Dockable components that are embedded within DockingPorts, especially during drag operations. As a Dockable is dragged over an DockingPort, this class allows the framework to determine with a single object instance any Dockables currently embedded within the target DockingPort, starting with the deepest Component at the current mouse point during the drag.

This classes' member fields are public and may be both accessed and modified by external code as needed within their particular usage context. This is by design for ease of use within the FlexDock framework. Consequently, instances of this class should only be used for short-lived operations. Since its member fields may be modified publicly, instances of this class should not be cached, nor should its member values be indexed as they are subject to arbitrary changes over the long term.

Author:
Christopher Butler

Field Summary
 Component child
           
 Component parent
           
 Component searchSrc
           
 
Method Summary
 boolean equals(Object obj)
          Returns true if the specified Object is a NestedComponents instance and all shares all of the same field references (==) as this NestedComponents for field searchSrc, child, and parent.
static NestedComponents find(Component searchSrc, Class childClass, Class parentClass)
          Creates and returns a new NestedComponents instance, searching the parent Container hierarcy of the specified searchSrc for an ancestor of type childClass and a more senior ancestor of type parentClass.
 int hashCode()
          Overridden to match the equals() method.
 boolean isFull()
          Returns true if both child and parent fields are non-null; false otherwise.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

searchSrc

public Component searchSrc

child

public Component child

parent

public Component parent
Method Detail

find

public static NestedComponents find(Component searchSrc,
                                    Class childClass,
                                    Class parentClass)
Creates and returns a new NestedComponents instance, searching the parent Container hierarcy of the specified searchSrc for an ancestor of type childClass and a more senior ancestor of type parentClass.

If either searchSrc, childClass, or parentClass is null, this method returns null.

If searchSrc is an instanceof childClass, then the child field on the resulting NestedComponents will be equal (==) to the searchSrc field. If searchSrc is an instanceof parentClass, then the parent field on the resulting NestedComponents will be equal (==) to the searchSrc field. If an instance of parentClass is found before childClass, this the resulting NestedComponents instance will have a null child field.

Parameters:
searchSrc - the Component from which to start searching for parent Containers.
childClass - the Class of the desired "child" Component
parentClass - the Class of the desired "parent" Component
Returns:
a new NestedComponents instance based upon the specified parameters.

isFull

public boolean isFull()
Returns true if both child and parent fields are non-null; false otherwise.

Returns:
true if both child and parent fields are non-null; false otherwise.

hashCode

public int hashCode()
Overridden to match the equals() method.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
equals(Object)

equals

public boolean equals(Object obj)
Returns true if the specified Object is a NestedComponents instance and all shares all of the same field references (==) as this NestedComponents for field searchSrc, child, and parent.

Overrides:
equals in class Object
Parameters:
obj - the Object to test for equality
Returns:
true if the specified Object is "equal" to this NestedComponents instance; false otherwise.