001    /*
002     * Created on Oct 31, 2007
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005     * in compliance with 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
010     * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011     * or implied. See the License for the specific language governing permissions and limitations under
012     * the License.
013     *
014     * Copyright @2007-2010 the original author or authors.
015     */
016    package org.fest.swing.hierarchy;
017    
018    import static java.awt.AWTEvent.COMPONENT_EVENT_MASK;
019    import static java.awt.AWTEvent.WINDOW_EVENT_MASK;
020    import static java.util.Collections.emptyList;
021    import static org.fest.swing.listener.WeakEventListener.attachAsWeakEventListener;
022    
023    import java.awt.*;
024    import java.util.Collection;
025    
026    import org.fest.swing.annotation.RunsInCurrentThread;
027    import org.fest.util.VisibleForTesting;
028    
029    /**
030     * Understands isolation of a component hierarchy to limit to only those components created during the lifetime of this
031     * hierarchy. Existing components (and any subsequently generated subwindows) are ignored by default.
032     * <p>
033     * Implicitly auto-filters windows which are disposed (i.e. generate a
034     * <code>{@link java.awt.event.WindowEvent#WINDOW_CLOSED WINDOW_CLOSED}</code> event), but also implicitly un-filters
035     * them if they should be shown again. Any window explicitly disposed by the calling
036     * <code>{@link ComponentHierarchy#dispose(java.awt.Window)}</code< will be ignored permanently.
037     * </p>
038     *
039     * @author Alex Ruiz
040     */
041    public class NewHierarchy extends ExistingHierarchy {
042    
043      private final WindowFilter filter;
044      private final TransientWindowListener transientWindowListener;
045    
046      /**
047       * Creates a new <code>{@link NewHierarchy}</code> which does not contain any existing GUI components.
048       * @return the created hierarchy.
049       */
050      public static NewHierarchy ignoreExistingComponents() {
051        return new NewHierarchy(true);
052      }
053    
054      /**
055       * Creates a new <code>{@link NewHierarchy}</code> which contains existing GUI components.
056       * @return the created hierarchy.
057       */
058      public static NewHierarchy includeExistingComponents() {
059        return new NewHierarchy(false);
060      }
061    
062      private NewHierarchy(boolean ignoreExisting) {
063        this(Toolkit.getDefaultToolkit(), ignoreExisting);
064      }
065    
066      private NewHierarchy(Toolkit toolkit, boolean ignoreExisting) {
067        this.filter = new WindowFilter(parentFinder(), childrenFinder());
068        transientWindowListener = new TransientWindowListener(filter);
069        setUp(toolkit, ignoreExisting);
070      }
071    
072      @VisibleForTesting
073      NewHierarchy(Toolkit toolkit, WindowFilter filter, boolean ignoreExisting) {
074        this.filter = filter;
075        transientWindowListener = new TransientWindowListener(filter);
076        setUp(toolkit, ignoreExisting);
077      }
078    
079      @RunsInCurrentThread
080      private void setUp(Toolkit toolkit, boolean ignoreExisting) {
081        if (ignoreExisting) ignoreExisting();
082        attachAsWeakEventListener(toolkit, transientWindowListener, WINDOW_EVENT_MASK | COMPONENT_EVENT_MASK);
083      }
084    
085      /**
086       * Make all currently existing components invisible to this hierarchy, without affecting their current state.
087       * <p>
088       * <b>Note:</b> This method is <b>not</b> guaranteed to be executed in the event dispatch thread (EDT.) Clients are
089       * responsible for calling this method from the EDT.
090       * </p>
091       */
092      @RunsInCurrentThread
093      public void ignoreExisting() {
094        for (Container c : roots())
095          filter.ignore(c);
096      }
097    
098      /**
099       * Make the given component visible to this hierarchy.
100       * <p>
101       * <b>Note:</b> This method is <b>not</b> guaranteed to be executed in the event dispatch thread (EDT.) Clients are
102       * responsible for calling this method from the EDT.
103       * </p>
104       * @param c the given component.
105       */
106      @RunsInCurrentThread
107      public void recognize(Component c) {
108        filter.recognize(c);
109      }
110    
111      /**
112       * Returns all sub-components of the given component, omitting those which are currently filtered.
113       * <p>
114       * <b>Note:</b> This method is <b>not</b> guaranteed to be executed in the event dispatch thread (EDT.) Clients are
115       * responsible for calling this method from the EDT.
116       * </p>
117       * @param c the given component.
118       * @return all sub-components of the given component, omitting those which are currently filtered.
119       */
120      @RunsInCurrentThread
121      @Override public Collection<Component> childrenOf(Component c) {
122        if (filter.isIgnored(c)) return emptyList();
123        Collection<Component> children = super.childrenOf(c);
124        // this only removes those components which are directly filtered, not necessarily those which have a filtered
125        // ancestor.
126        children.removeAll(filter.filtered());
127        return children;
128      }
129    
130      /**
131       * Returns <code>true</code> if the given component is not filtered.
132       * <p>
133       * <b>Note:</b> This method is <b>not</b> guaranteed to be executed in the event dispatch thread (EDT.) Clients are
134       * responsible for calling this method from the EDT.
135       * </p>
136       * @param c the given component.
137       * @return <code>true</code> if the given component is not filtered, <code>false</code> otherwise.
138       */
139      @RunsInCurrentThread
140      @Override public boolean contains(Component c) {
141        return super.contains(c) && !filter.isIgnored(c);
142      }
143    
144      /**
145       * Dispose of the given window, but only if it currently exists within the hierarchy.  It will no longer appear in
146       * <p>
147       * <b>Note:</b> This method is <b>not</b> guaranteed to be executed in the event dispatch thread (EDT.) Clients are
148       * responsible for calling this method from the EDT.
149       * </p>
150       * this hierarchy or be reachable in a hierarchy walk.
151       * @param w the window to dispose.
152       */
153      @RunsInCurrentThread
154      @Override public void dispose(Window w) {
155        if (!contains(w)) return;
156        super.dispose(w);
157        filter.ignore(w);
158      }
159    
160      /**
161       * Returns all available root containers, excluding those which have been filtered.
162       * @return  all available root containers, excluding those which have been filtered.
163       */
164      @Override public Collection<? extends Container> roots() {
165        Collection<? extends Container> roots = super.roots();
166        roots.removeAll(filter.filtered());
167        return roots;
168      }
169    }