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<JOptionPane> matcher = new GenericTypeMatcher<JOptionPane>() {
062 * protected boolean isMatching(JOptionPane optionPane) {
063 * return "A message".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 }