org.flexdock.util

## Class NestedComponents

- java.lang.Object
- - org.flexdock.util.NestedComponents

    public class NestedComponents
    extends java.lang.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

Fields
`java.awt.Component` `child`
`java.awt.Component` `parent`
`java.awt.Component` `searchSrc`

### Method Summary

Methods
`boolean` `equals(java.lang.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(java.awt.Component searchSrc, java.lang.Class childClass, java.lang.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 java.awt.Component searchSrc

#### child

    public java.awt.Component child

#### parent

    public java.awt.Component parent

### Method Detail

#### find

    public static NestedComponents find(java.awt.Component searchSrc,
                        java.lang.Class childClass,
                        java.lang.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 `java.lang.Object`
Returns:
  a hash code value for this object.
See Also:
  `equals(Object)`

#### equals

    public boolean equals(java.lang.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 `java.lang.Object`
Parameters:
  `obj` - the `Object` to test for equality
Returns:
  `true` if the specified `Object` is "equal" to this `NestedComponents` instance; `false` otherwise.