001    /*
002     * Created on Oct 19, 2007
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
005     * the License. You may obtain a copy of the License at
006     *
007     * http://www.apache.org/licenses/LICENSE-2.0
008     *
009     * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
010     * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
011     * specific language governing permissions and limitations under the License.
012     *
013     * Copyright @2007-2010 the original author or authors.
014     */
015    package org.fest.swing.hierarchy;
016    
017    import java.awt.*;
018    import java.util.Collection;
019    
020    import org.fest.swing.annotation.RunsInCurrentThread;
021    
022    /**
023     * Understands access to all components in a hierarchy. <b>Note:</b> Methods in this class are <b>not</b> executed in
024     * the event dispatch thread. Callers are responsible for calling them in the event dispatch thread.
025     * <p>
026     * <b>Note:</b> methods in this interface are <b>not</b> guaranteed to be executed in the event dispatch thread (EDT.)
027     * Clients are responsible for invoking them in the EDT.
028     * </p>
029     *
030     * @author Alex Ruiz
031     * @author Yvonne Wang
032     */
033    @RunsInCurrentThread
034    public interface ComponentHierarchy {
035    
036      /**
037       * Provides all root containers in the hierarchy.
038       * @return all root containers in the hierarchy.
039       */
040      Collection<? extends Container> roots();
041    
042      /**
043       * Returns all sub-components of the given component.
044       * @param c the given component.
045       * @return all sub-components of the given component.
046       */
047      Collection<Component> childrenOf(Component c);
048    
049      /**
050       * Return the parent for the given component.
051       * @param c the given component.
052       * @return the parent for the given component.
053       */
054      Container parentOf(Component c);
055    
056      /**
057       * Returns whether this hierarchy contains the given component.
058       * @param c the given component.
059       * @return <code>true</code> if this hierarchy contains the given component, <code>false</code> otherwise.
060       */
061      boolean contains(Component c);
062    
063      /**
064       * Provides proper disposal of the given window, appropriate to this hierarchy. After disposal, the window and its
065       * descendants will no longer be reachable from this hierarchy.
066       * @param w the container to window.
067       */
068      void dispose(Window w);
069    }