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.Dialog; 022 import java.util.regex.Pattern; 023 024 import org.fest.swing.annotation.RunsInCurrentThread; 025 026 /** 027 * Understands matching a <code>{@link Dialog}</code> by name, title and visibility on the screen. 028 * 029 * @author Alex Ruiz 030 */ 031 public final class DialogMatcher extends NamedComponentMatcherTemplate<Dialog> { 032 033 private Object title; 034 035 /** 036 * Creates a new <code>{@link DialogMatcher}</code> that matches a <code>{@link Dialog}</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 Dialog}</code> by name and title: 043 * <pre> 044 * DialogMatcher m = {@link #withName(String) withName}("saveFile").{@link #andTitle(String) andTitle}("Save File"); 045 * </pre> 046 * </p> 047 * <p> 048 * The following code listing shows how to match a <code>{@link Dialog}</code>, that should be showing on the screen, 049 * by name and title: 050 * <pre> 051 * DialogMatcher m = {@link #withName(String) withName}("saveFile").{@link #andTitle(String) andTitle}("Save File").{@link #andShowing() andShowing}(); 052 * </pre> 053 * </p> 054 * @param name the id to match. 055 * @return the created matcher. 056 */ 057 public static DialogMatcher withName(String name) { 058 return new DialogMatcher(name, ANY); 059 } 060 061 /** 062 * Creates a new <code>{@link DialogMatcher}</code> that matches a <code>{@link Dialog}</code> by its title. 063 * <p> 064 * The following code listing shows how to match a <code>{@link Dialog}</code> title: 065 * <pre> 066 * DialogMatcher m = {@link #withTitle(String) withTitle}("Save File"); 067 * </pre> 068 * </p> 069 * <p> 070 * The following code listing shows how to match a <code>{@link Dialog}</code>, that should be showing on the screen, 071 * by title: 072 * <pre> 073 * DialogMatcher m = {@link #withTitle(String) withTitle}("Save File").{@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 DialogMatcher withTitle(String title) { 080 return new DialogMatcher(ANY, title); 081 } 082 083 /** 084 * Creates a new <code>{@link DialogMatcher}</code> that matches a <code>{@link Dialog}</code> by its title. 085 * <p> 086 * The following code listing shows how to match a <code>{@link Dialog}</code> title, using a regular expression 087 * pattern: 088 * <pre> 089 * DialogMatcher m = {@link #withTitle(Pattern) withTitle}(Pattern.compile("Sav.*")); 090 * </pre> 091 * </p> 092 * <p> 093 * The following code listing shows how to match a <code>{@link Dialog}</code>, that should be showing on the screen, 094 * by title, using a regular expression pattern: 095 * <pre> 096 * DialogMatcher m = {@link #withTitle(Pattern) withTitle}(Pattern.compile("Sav.*")).{@link #andShowing() andShowing}(); 097 * </pre> 098 * </p> 099 * @param titlePattern the regular expression pattern to match. 100 * @return the created matcher. 101 * @since 1.2 102 */ 103 public static DialogMatcher withTitle(Pattern titlePattern) { 104 return new DialogMatcher(ANY, titlePattern); 105 } 106 107 /** 108 * Creates a new <code>{@link DialogMatcher}</code> that matches any <code>{@link Dialog}</code>. 109 * @return the created matcher. 110 */ 111 public static DialogMatcher any() { 112 return new DialogMatcher(ANY, ANY); 113 } 114 115 private DialogMatcher(Object name, Object title) { 116 super(Dialog.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 #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 DialogMatcher andTitle(String newTitle) { 127 title = newTitle; 128 return this; 129 } 130 131 132 /** 133 * Specifies the title to match. If this matcher was created using <code>{@link #withTitle(String)}</code>, or 134 * <code>{@link #withTitle(Pattern)}</code> this method will simply update the title to match. 135 * @param titlePattern the regular expression pattern to match. 136 * @return this matcher. 137 * @since 1.2 138 */ 139 public DialogMatcher andTitle(Pattern titlePattern) { 140 title = titlePattern; 141 return this; 142 } 143 144 /** 145 * Indicates that the <code>{@link Dialog}</code> to match should be showing on the screen. 146 * @return this matcher. 147 */ 148 public DialogMatcher andShowing() { 149 requireShowing(true); 150 return this; 151 } 152 153 /** 154 * Indicates whether: 155 * <ul> 156 * <li>the name of the given <code>Dialog</code> is equal to the name in this matcher, and</li> 157 * <li>the title of the given <code>Dialog</code> matches the text (or pattern) in this matcher</li> 158 * </ul> 159 * <p> 160 * <b>Note:</b> This method is <b>not</b> guaranteed to be executed in the event dispatch thread (EDT.) Clients are 161 * responsible for calling this method from the EDT. 162 * </p> 163 * @param dialog the <code>Dialog</code> to match. 164 * @return <code>true</code> if the <code>Dialog</code> matches the search criteria in this matcher. 165 */ 166 @RunsInCurrentThread 167 protected boolean isMatching(Dialog dialog) { 168 if (!isNameMatching(dialog.getName())) return false; 169 return arePropertyValuesMatching(title, dialog.getTitle()); 170 } 171 172 @Override public String toString() { 173 return concat( 174 getClass().getName(), "[", 175 "name=", quotedName(), ", ", 176 "title=", quoted(title), ", ", 177 "requireShowing=", valueOf(requireShowing()), 178 "]" 179 ); 180 } 181 }