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 }