001    /*
002     * Created on Jul 30, 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.finder;
017    
018    import java.awt.Dialog;
019    import java.awt.Frame;
020    
021    import org.fest.swing.core.GenericTypeMatcher;
022    
023    /**
024     * <p>
025     * Understands lookup of <code>{@link Frame}</code>s and <code>{@link Dialog}</code>s. Lookups are performed till
026     * the window of interest is found, or until the given time to perform the lookup is over. The default lookup time is 5
027     * seconds.
028     * </p>
029     * <p>
030     * <code>{@link WindowFinder}</code> is the &quot;entry point&quot; of a fluent interface to look up frames and
031     * dialogs. This example illustrates finding a <code>{@link Frame}</code> by name, using the default lookup time (5
032     * seconds):
033     *
034     * <pre>
035     * FrameFixture frame = WindowFinder.findFrame(&quot;someFrame&quot;).using(robot);
036     * </pre>
037     *
038     * </p>
039     * <p>
040     * Where <code>robot</code> is an instance of <code>{@link org.fest.swing.core.Robot}</code>.
041     * </p>
042     * <p>
043     * This example shows how to find a <code>{@link Dialog}</code> by type using a lookup time of 10 seconds:
044     *
045     * <pre>
046     * DialogFixture dialog = WindowFinder.findDialog(MyDialog.class).withTimeout(10000).using(robot);
047     * </pre>
048     *
049     * We can also specify the time unit:
050     *
051     * <pre>
052     * DialogFixture dialog = WindowFinder.findDialog(MyDialog.class).withTimeout(10, {@link java.util.concurrent.TimeUnit#SECONDS SECONDS}).using(robot);
053     * </pre>
054     *
055     * </p>
056     * <p>
057     * This example shows how to use a <code>{@link GenericTypeMatcher}</code> to find a <code>{@link Frame}</code> with
058     * title "Hello":
059     *
060     * <pre>
061     * GenericTypeMatcher&lt;JFrame&gt; matcher = new GenericTypeMatcher&lt;JFrame&gt;() {
062     *   protected boolean isMatching(JFrame frame) {
063     *     return &quot;hello&quot;.equals(frame.getTitle());
064     *   }
065     * };
066     * FrameFixture frame = WindowFinder.findFrame(matcher).using(robot);
067     * </pre>
068     *
069     * </p>
070     *
071     * @author Alex Ruiz
072     * @author Yvonne Wang
073     */
074    public final class WindowFinder {
075    
076      private WindowFinder() {}
077    
078      /**
079       * Creates a new <code>{@link FrameFinder}</code> capable of looking up a <code>{@link Frame}</code> by name.
080       * @param frameName the name of the frame to find.
081       * @return the created finder.
082       */
083      public static FrameFinder findFrame(String frameName) {
084        return new FrameFinder(frameName);
085      }
086    
087      /**
088       * Creates a new <code>{@link FrameFinder}</code> capable of looking up a <code>{@link Frame}</code> by type.
089       * @param frameType the type of the frame to find.
090       * @return the created finder.
091       */
092      public static FrameFinder findFrame(Class<? extends Frame> frameType) {
093        return new FrameFinder(frameType);
094      }
095    
096      /**
097       * Creates a new <code>{@link FrameFinder}</code> capable of looking up a <code>{@link Frame}</code> using the
098       * provided matcher.
099       * @param matcher the matcher to use to find a frame.
100       * @return the created finder.
101       */
102      public static FrameFinder findFrame(GenericTypeMatcher<? extends Frame> matcher) {
103        return new FrameFinder(matcher);
104      }
105    
106      /**
107       * Creates a new <code>{@link DialogFinder}</code> capable of looking up a <code>{@link Dialog}</code> by name.
108       * @param dialogName the name of the dialog to find.
109       * @return the created finder.
110       */
111      public static DialogFinder findDialog(String dialogName) {
112        return new DialogFinder(dialogName);
113      }
114    
115      /**
116       * Creates a new <code>{@link DialogFinder}</code> capable of looking up a <code>{@link Dialog}</code> by type.
117       * @param dialogType the type of the dialog to find.
118       * @return the created finder.
119       */
120      public static DialogFinder findDialog(Class<? extends Dialog> dialogType) {
121        return new DialogFinder(dialogType);
122      }
123    
124      /**
125       * Creates a new <code>{@link DialogFinder}</code> capable of looking up a <code>{@link Dialog}</code> using the
126       * provided matcher.
127       * @param matcher the matcher to use to find a dialog.
128       * @return the created finder.
129       */
130      public static DialogFinder findDialog(GenericTypeMatcher<? extends Dialog> matcher) {
131        return new DialogFinder(matcher);
132      }
133    }