001 /*
002 * Created on Jul 16, 2008
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 @2008-2010 the original author or authors.
015 */
016 package org.fest.swing.core.matcher;
017
018 import static java.lang.String.valueOf;
019 import static org.fest.util.Strings.concat;
020
021 import java.awt.Frame;
022 import java.util.regex.Pattern;
023
024 import org.fest.swing.annotation.RunsInCurrentThread;
025
026 /**
027 * Understands matching a <code>{@link Frame}</code> by type, name or title.
028 *
029 * @author Alex Ruiz
030 */
031 public final class FrameMatcher extends NamedComponentMatcherTemplate<Frame> {
032
033 private Object title;
034
035 /**
036 * Creates a new <code>{@link FrameMatcher}</code> that matches a <code>{@link Frame}</code> that:
037 * <ol>
038 * <li>has a matching name</li>
039 * <li>(optionally) has matching title</li>
040 * <li>(optionally) is showing on the screen</li>
041 * <p>
042 * The following code listing shows how to match a <code>{@link Frame}</code> by name and title:
043 * <pre>
044 * FrameMatcher m = {@link #withName(String) withName}("myApp").{@link #andTitle(String) andTitle}("My App");
045 * </pre>
046 * </p>
047 * <p>
048 * The following code listing shows how to match a <code>{@link Frame}</code>, that should be showing on the screen,
049 * by name and title:
050 * <pre>
051 * FrameMatcher m = {@link #withName(String) withName}("myApp").{@link #andTitle(String) andTitle}("My App").{@link #andShowing() andShowing}();
052 * </pre>
053 * </p>
054 * @param name the id to match.
055 * @return the created matcher.
056 */
057 public static FrameMatcher withName(String name) {
058 return new FrameMatcher(name, ANY);
059 }
060
061 /**
062 * Creates a new <code>{@link FrameMatcher}</code> that matches a <code>{@link Frame}</code> by its title.
063 * <p>
064 * The following code listing shows how to match a <code>{@link Frame}</code> by title:
065 * <pre>
066 * FrameMatcher m = {@link #withTitle(String) withTitle}("My App");
067 * </pre>
068 * </p>
069 * <p>
070 * The following code listing shows how to match a <code>{@link Frame}</code>, that should be showing on the screen,
071 * by title:
072 * <pre>
073 * FrameMatcher m = {@link #withTitle(String) withTitle}("My App").{@link #andShowing() andShowing}();
074 * </pre>
075 * </p>
076 * @param title the title to match. It can be a regular expression.
077 * @return the created matcher.
078 */
079 public static FrameMatcher withTitle(String title) {
080 return new FrameMatcher(ANY, title);
081 }
082
083 /**
084 * Creates a new <code>{@link FrameMatcher}</code> that matches a <code>{@link Frame}</code> by its title.
085 * <p>
086 * The following code listing shows how to match a <code>{@link Frame}</code> by title, using a regular expression
087 * matcher:
088 * <pre>
089 * FrameMatcher m = {@link #withTitle(Pattern) withTitle}(Pattern.compile("My.*"));
090 * </pre>
091 * </p>
092 * <p>
093 * The following code listing shows how to match a <code>{@link Frame}</code>, that should be showing on the screen,
094 * by title:
095 * <pre>
096 * FrameMatcher m = {@link #withTitle(Pattern) withTitle}(Pattern.compile("My.*")).{@link #andShowing() andShowing}();
097 * </pre>
098 * </p>
099 * @param titlePattern the title to match.
100 * @return the created matcher.
101 * @since 1.2
102 */
103 public static FrameMatcher withTitle(Pattern titlePattern) {
104 return new FrameMatcher(ANY, titlePattern);
105 }
106
107 /**
108 * Creates a new <code>{@link FrameMatcher}</code> that matches any <code>{@link Frame}</code>.
109 * @return the created matcher.
110 */
111 public static FrameMatcher any() {
112 return new FrameMatcher(ANY, ANY);
113 }
114
115 private FrameMatcher(Object name, Object title) {
116 super(Frame.class, name);
117 this.title = title;
118 }
119
120 /**
121 * Specifies the title to match. If this matcher was created using <code>{@link #withTitle(String)}</code> or
122 * <code>{@link FrameMatcher#withTitle(Pattern)}</code>, this method will simply update the title to match.
123 * @param newTitle the new title to match. It can be a regular expression.
124 * @return this matcher.
125 */
126 public FrameMatcher andTitle(String newTitle) {
127 title = newTitle;
128 return this;
129 }
130
131 /**
132 * Specifies the title to match. If this matcher was created using <code>{@link #withTitle(String)}</code> or
133 * <code>{@link FrameMatcher#withTitle(Pattern)}</code>, this method will simply update the title to match.
134 * @param titlePattern the regular expression pattern to match.
135 * @return this matcher.
136 * @since 1.2
137 */
138 public FrameMatcher andTitle(Pattern titlePattern) {
139 title = titlePattern;
140 return this;
141 }
142
143 /**
144 * Indicates that the <code>{@link Frame}</code> to match should be showing on the screen.
145 * @return this matcher.
146 */
147 public FrameMatcher andShowing() {
148 requireShowing(true);
149 return this;
150 }
151
152 /**
153 * Indicates whether the title of the given <code>{@link Frame}</code> is equal to the title in this matcher.
154 * <p>
155 * <b>Note:</b> This method is <b>not</b> guaranteed to be executed in the event dispatch thread (EDT.) Clients are
156 * responsible for calling this method from the EDT.
157 * </p>
158 * @param frame the <code>Frame</code> to match.
159 * @return <code>true</code> if the title in the <code>Frame</code> is equal to the title in this matcher,
160 * <code>false</code> otherwise.
161 */
162 @RunsInCurrentThread
163 protected boolean isMatching(Frame frame) {
164 if (!isNameMatching(frame.getName())) return false;
165 return arePropertyValuesMatching(title, frame.getTitle());
166 }
167
168 @Override public String toString() {
169 return concat(
170 getClass().getName(), "[",
171 "name=", quotedName(), ", ",
172 "title=", quoted(title), ", ",
173 "requireShowing=", valueOf(requireShowing()),
174 "]"
175 );
176 }
177 }