001    /*
002     * Created on Oct 29, 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.Component;
019    import java.util.concurrent.TimeUnit;
020    
021    import javax.swing.JOptionPane;
022    
023    import org.fest.swing.core.GenericTypeMatcher;
024    import org.fest.swing.core.Robot;
025    import org.fest.swing.fixture.JOptionPaneFixture;
026    
027    /**
028     * Understands a finder for <code>{@link JOptionPane}</code>s. Lookups are performed till a file chooser is found, or
029     * until the given time to perform the lookup is over. The default lookup time is 5 seconds.
030     * </p>
031     * <p>
032     * This example illustrates finding a <code>{@link JOptionPane}</code> by name, using the default lookup time (5
033     * seconds):
034     *
035     * <pre>
036     * JOptionPaneFixture optionPane = JOptionPaneFinder.findOptionPane().using(robot);
037     * </pre>
038     *
039     * </p>
040     * <p>
041     * Where <code>robot</code> is an instance of <code>{@link org.fest.swing.core.Robot}</code>.
042     * </p>
043     * <p>
044     * This example shows how to find a <code>{@link JOptionPane}</code> by type using a lookup time of 10 seconds:
045     *
046     * <pre>
047     * JOptionPaneFixture optionPane = JOptionPaneFinder.findOptionPane().withTimeout(10000).using(robot);
048     * </pre>
049     *
050     * We can also specify the time unit:
051     *
052     * <pre>
053     * JOptionPaneFixture optionPane = JOptionPaneFinder.findOptionPane().withTimeout(10, {@link TimeUnit#SECONDS SECONDS}).using(robot);
054     * </pre>
055     *
056     * </p>
057     * <p>
058     * This example shows how to find a <code>{@link JOptionPane}</code> using a <code>{@link GenericTypeMatcher}</code>:
059     *
060     * <pre>
061     * GenericTypeMatcher&lt;JOptionPane&gt; matcher = new GenericTypeMatcher&lt;JOptionPane&gt;() {
062     *   protected boolean isMatching(JOptionPane optionPane) {
063     *     return &quot;A message&quot;.equals(optionPane.getMessage());
064     *   }
065     * };
066     * JOptionPaneFixture optionPane = JOptionPaneFinder.findOptionPane(matcher).using(robot);
067     * </pre>
068     *
069     * </p>
070     *
071     * @author Yvonne Wang
072     * @author Alex Ruiz
073     */
074    public class JOptionPaneFinder extends ComponentFinderTemplate<JOptionPane> {
075    
076      /**
077       * Creates a new </code>{@link JOptionPaneFinder}</code>. This finder looks up a <code>{@link JOptionPane}</code> by
078       * type.
079       */
080      protected JOptionPaneFinder() {
081        super(JOptionPane.class);
082      }
083    
084      /**
085       * Creates a new </code>{@link JOptionPaneFinder}</code>.
086       * @param matcher specifies the search criteria to use when looking up a {@code JOptionPane}.
087       */
088      protected JOptionPaneFinder(GenericTypeMatcher<? extends JOptionPane> matcher) {
089        super(matcher);
090      }
091    
092      /**
093       * Creates a new <code>{@link JOptionPaneFinder}</code> capable of looking up a <code>{@link JOptionPane}</code>.
094       * @return the created finder.
095       */
096      public static JOptionPaneFinder findOptionPane() {
097        return new JOptionPaneFinder();
098      }
099    
100      /**
101       * Creates a new <code>{@link JOptionPaneFinder}</code> capable of looking up a <code>{@link JOptionPane}</code>
102       * using the given matcher.
103       * @param matcher the given matcher.
104       * @return the created finder.
105       */
106      public static JOptionPaneFinder findOptionPane(GenericTypeMatcher<? extends JOptionPane> matcher) {
107        return new JOptionPaneFinder(matcher);
108      }
109    
110      /**
111       * Finds a <code>{@link JOptionPane}</code> by name or type.
112       * @param robot contains the underlying finding to delegate the search to.
113       * @return a <code>JOptionPaneFixture</code> managing the found <code>JOptionPane</code>.
114       * @throws org.fest.swing.exception.WaitTimedOutError if a <code>JOptionPane</code> could not be found.
115       */
116      public JOptionPaneFixture using(Robot robot) {
117        return new JOptionPaneFixture(robot, findComponentWith(robot));
118      }
119    
120      /**
121       * Sets the timeout for this finder. The window to search should be found within the given time period.
122       * @param timeout the number of milliseconds before stopping the search.
123       * @return this finder.
124       */
125      @Override public JOptionPaneFinder withTimeout(long timeout) {
126        super.withTimeout(timeout);
127        return this;
128      }
129    
130      /**
131       * Sets the timeout for this finder. The window to search should be found within the given time period.
132       * @param timeout the period of time the search should be performed.
133       * @param unit the time unit for <code>timeout</code>.
134       * @return this finder.
135       */
136      @Override public JOptionPaneFinder withTimeout(long timeout, TimeUnit unit) {
137        super.withTimeout(timeout, unit);
138        return this;
139      }
140    
141      /**
142       * Casts the given {@code Component} to <code>{@link JOptionPane}</code>.
143       * @return the given {@code Component}, casted to {@code JFileChooser}.
144       */
145      protected JOptionPane cast(Component c) { return (JOptionPane) c; }
146    }