org.assertj.swing.core

Interface ComponentFinder

All Known Implementing Classes:

BasicComponentFinder

@RunsInEDT
public interface ComponentFinder

Looks up AWT and Swing Components based on different search criteria, such as a Component's name, type or label, and custom search criteria as well.

Author:

Alex Ruiz

Method Summary

Methods

Modifier and Type	Method and Description
Component	find(ComponentMatcher m) Finds an AWT or Swing Component using the given ComponentMatcher.
Component	find(Container root, ComponentMatcher m) Finds an AWT or Swing Component using the given ComponentMatcher in the hierarchy under the given root.
<T extends Component> T	find(Container root, GenericTypeMatcher<T> m) Finds an AWT or Swing Component using the given GenericTypeMatcher in the hierarchy under the given root.
<T extends Component> T	find(GenericTypeMatcher<T> m) Finds an AWT or Swing Component using the given GenericTypeMatcher.
Collection<Component>	findAll(ComponentMatcher m) Returns all the AWT or Swing Components that match the search criteria specified in the given ComponentMatcher.
Collection<Component>	findAll(Container root, ComponentMatcher m) Returns all the AWT or Swing Components under the given root that match the search criteria specified in the given ComponentMatcher.
<T extends Component> Collection<T>	findAll(Container root, GenericTypeMatcher<T> m) Returns all the AWT or Swing Components under the given root that match the search criteria specified in the given GenericTypeMatcher.
<T extends Component> Collection<T>	findAll(GenericTypeMatcher<T> m) Returns all the AWT or Swing Components that match the search criteria specified in the given GenericTypeMatcher.
Component	findByLabel(Container root, String label) Finds an AWT or Swing Component by the text of its associated JLabel, in the hierarchy under the given root.
Component	findByLabel(Container root, String label, boolean showing) Finds an AWT or Swing Component by the text of its associated JLabel, in the hierarchy under the given root.
<T extends Component> T	findByLabel(Container root, String label, Class<T> type) Finds an AWT or Swing Component by the text of its associated JLabel and type, in the hierarchy under the given root.
<T extends Component> T	findByLabel(Container root, String label, Class<T> type, boolean showing) Finds an AWT or Swing Component by the text of its associated JLabel and type, in the hierarchy under the given root.
Component	findByLabel(String label) Finds an AWT or Swing Component by by the text of its associated JLabel.
Component	findByLabel(String label, boolean showing) Finds an AWT or Swing Component by by the text of its associated JLabel.
<T extends Component> T	findByLabel(String label, Class<T> type) Finds an AWT or Swing Component by the text of its associated JLabel and type.
<T extends Component> T	findByLabel(String label, Class<T> type, boolean showing) Finds an AWT or Swing Component by the text of its associated JLabel and type.
Component	findByName(Container root, String name) Finds an AWT or Swing Component by name, in the hierarchy under the given root.
Component	findByName(Container root, String name, boolean showing) Finds an AWT or Swing Component by name, in the hierarchy under the given root.
<T extends Component> T	findByName(Container root, String name, Class<T> type) Finds an AWT or Swing Component by name and type, in the hierarchy under the given root.
<T extends Component> T	findByName(Container root, String name, Class<T> type, boolean showing) Finds an AWT or Swing Component by name and type, in the hierarchy under the given root.
Component	findByName(String name) Finds an AWT or Swing Component by name.
Component	findByName(String name, boolean showing) Finds an AWT or Swing Component by name.
<T extends Component> T	findByName(String name, Class<T> type) Finds an AWT or Swing Component by name and type.
<T extends Component> T	findByName(String name, Class<T> type, boolean showing) Finds an AWT or Swing Component by name and type.
<T extends Component> T	findByType(Class<T> type) Finds an AWT or Swing Component by type.
<T extends Component> T	findByType(Class<T> type, boolean showing) Finds an AWT or Swing Component by type.
<T extends Component> T	findByType(Container root, Class<T> type) Finds an AWT or Swing Component by type in the hierarchy under the given root.
<T extends Component> T	findByType(Container root, Class<T> type, boolean showing) Finds an AWT or Swing Component by type in the hierarchy under the given root.
boolean	includeHierarchyIfComponentNotFound() Returns whether the message in a ComponentLookupException should include the current component hierarchy.
void	includeHierarchyIfComponentNotFound(boolean newValue) Updates whether the message in a ComponentLookupException should include the current component hierarchy.
ComponentPrinter	printer()

Method Detail

printer

@Nonnull
ComponentPrinter printer()

Returns:

the ComponentPrinter in this finder.

findByType

@Nonnull
<T extends Component> T findByType(@Nonnull
                                         Class<T> type)

Finds an AWT or Swing Component by type. If this finder is attached to a Robot, it will use the component lookup scope in the Robot's Settings to determine whether the component to find should be showing or not. If this finder is not attached to any Robot, the component to find does not have to be showing.

Example:

 JTextField textbox = finder.findByType(JTextField.class);
 

Parameters:

type - the type of the component to find.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

Robot.settings(), Settings.componentLookupScope(), ComponentLookupScope

findByType

@Nonnull
<T extends Component> T findByType(@Nonnull
                                         Class<T> type,
                                         boolean showing)

Finds an AWT or Swing Component by type. For example:

Parameters:

type - the type of the component to find.

showing - indicates whether the component to find should be visible (or showing) or not.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByType(Class)

findByType

@Nonnull
<T extends Component> T findByType(@Nonnull
                                         Container root,
                                         @Nonnull
                                         Class<T> type)

Finds an AWT or Swing Component by type in the hierarchy under the given root. If this finder is attached to a Robot, it will use the component lookup scope in the Robot's Settings to determine whether the component to find should be showing or not. If this finder is not attached to any Robot, the component to find does not have to be showing.

Let's assume we have the following JFrame containing a JTextField:

 JFrame myFrame = new JFrame();
 myFrame.add(new JTextField());
 

If we want to get a reference to the JTextField in that particular JFrame without going through the whole AWT component hierarchy, we could simply specify:

 JTextField textbox = finder.findByType(myFrame, JTextField.class);
 

Parameters:

root - the root used as the starting point of the search.

type - the type of the component to find.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

Robot.settings(), Settings.componentLookupScope(), ComponentLookupScope

findByType

@Nonnull
<T extends Component> T findByType(@Nonnull
                                         Container root,
                                         @Nonnull
                                         Class<T> type,
                                         boolean showing)

Finds an AWT or Swing Component by type in the hierarchy under the given root.

Parameters:

root - the root used as the starting point of the search.

showing - indicates whether the component to find should be visible (or showing) or not.

type - the type of the component to find.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByType(Container, Class)

findByLabel

@Nonnull
Component findByLabel(@Nullable
                            String label)

Finds an AWT or Swing Component by by the text of its associated JLabel. If this finder is attached to a Robot, it will use the component lookup scope in the Robot's Settings to determine whether the component to find should be showing or not. If this finder is not attached to any Robot, the component to find does not have to be showing.

Let's assume we have the JTextField with a JLabel with text "Name";

 JLabel label = new JLabel("Name");
 JTextField textbox = new JTextField();
 label.setLabelFor(textBox);
 

To get a reference to this JTextField by the text of its associated JLabel, we can specify:

 JTextField textBox = (JTextField) finder.findByLabel("Name");
 

Please note that you need to cast the result of the lookup to the right type. To avoid casting, please use one of following:

1. findByLabel(String, Class)
2. findByLabel(String, Class, boolean)
3. findByLabel(Container, String, Class)
4. findByLabel(Container, String, Class, boolean)

Parameters:

label - the text of the JLabel associated to the component to find.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

JLabel.getLabelFor(), JLabel.setLabelFor(Component), Robot.settings(), Settings.componentLookupScope(), ComponentLookupScope

findByLabel

@Nonnull
<T extends Component> T findByLabel(@Nullable
                                          String label,
                                          @Nonnull
                                          Class<T> type)

Finds an AWT or Swing Component by the text of its associated JLabel and type. If this finder is attached to a Robot, it will use the component lookup scope in the Robot's Settings to determine whether the component to find should be showing or not. If this finder is not attached to any Robot, the component to find does not have to be showing.

Parameters:

label - the text of the JLabel associated to the component to find.

type - the type of the component to find.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByLabel(String), JLabel.getLabelFor(), JLabel.setLabelFor(Component), Robot.settings(), Settings.componentLookupScope(), ComponentLookupScope

findByLabel

@Nonnull
<T extends Component> T findByLabel(@Nullable
                                          String label,
                                          @Nonnull
                                          Class<T> type,
                                          boolean showing)

Finds an AWT or Swing Component by the text of its associated JLabel and type.

Parameters:

label - the text of the JLabel associated to the component to find.

type - the type of the component to find.

showing - indicates whether the component to find should be visible (or showing) or not.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByLabel(String), JLabel.getLabelFor(), JLabel.setLabelFor(Component)

findByLabel

@Nonnull
Component findByLabel(@Nullable
                            String label,
                            boolean showing)

Finds an AWT or Swing Component by by the text of its associated JLabel.

Parameters:

label - the text of the JLabel associated to the component to find.

showing - indicates whether the component to find should be visible (or showing) or not.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByLabel(String), JLabel.getLabelFor(), JLabel.setLabelFor(Component)

findByLabel

@Nonnull
Component findByLabel(@Nonnull
                            Container root,
                            @Nullable
                            String label)

Finds an AWT or Swing Component by the text of its associated JLabel, in the hierarchy under the given root. If this finder is attached to a Robot, it will use the component lookup scope in the Robot's Settings to determine whether the component to find should be showing or not. If this finder is not attached to any Robot, the component to find does not have to be showing.

Parameters:

root - the root used as the starting point of the search.

label - the text of the JLabel associated to the component to find.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByLabel(String), JLabel.getLabelFor(), JLabel.setLabelFor(Component), Robot.settings(), Settings.componentLookupScope(), ComponentLookupScope

findByLabel

@Nonnull
Component findByLabel(@Nonnull
                            Container root,
                            @Nullable
                            String label,
                            boolean showing)

Finds an AWT or Swing Component by the text of its associated JLabel, in the hierarchy under the given root.

Parameters:

root - the root used as the starting point of the search.

label - the text of the JLabel associated to the component to find.

showing - indicates whether the component to find should be visible (or showing) or not.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByLabel(String), JLabel.getLabelFor(), JLabel.setLabelFor(Component)

findByLabel

@Nonnull
<T extends Component> T findByLabel(@Nonnull
                                          Container root,
                                          @Nullable
                                          String label,
                                          @Nonnull
                                          Class<T> type)

Finds an AWT or Swing Component by the text of its associated JLabel and type, in the hierarchy under the given root. If this finder is attached to a Robot, it will use the component lookup scope in the Robot's Settings to determine whether the component to find should be showing or not. If this finder is not attached to any Robot, the component to find does not have to be showing.

Parameters:

root - the root used as the starting point of the search.

label - the text of the JLabel associated to the component to find.

type - the type of the component to find.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByLabel(String), JLabel.getLabelFor(), JLabel.setLabelFor(Component), Robot.settings(), Settings.componentLookupScope(), ComponentLookupScope

findByLabel

@Nonnull
<T extends Component> T findByLabel(@Nonnull
                                          Container root,
                                          @Nullable
                                          String label,
                                          @Nonnull
                                          Class<T> type,
                                          boolean showing)

Finds an AWT or Swing Component by the text of its associated JLabel and type, in the hierarchy under the given root.

Parameters:

root - the root used as the starting point of the search.

label - the text of the JLabel associated to the component to find.

type - the type of the component to find.

showing - indicates whether the component to find should be visible (or showing) or not.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByLabel(String), JLabel.getLabelFor(), JLabel.setLabelFor(Component)

findByName

@Nonnull
Component findByName(@Nullable
                           String name)

Finds an AWT or Swing Component by name. If this finder is attached to a Robot, it will use the component lookup scope in the Robot's Settings to determine whether the component to find should be showing or not. If this finder is not attached to any Robot, the component to find does not have to be showing.

Let's assume we have the JTextField with name "myTextBox";

 JTextField textbox = new JTextField();
 textBox.setName("myTextBox");
 

To get a reference to this JTextField by its name, we can specify:

 JTextField textBox = (JTextField) finder.findByName("myTextBox");
 

Please note that you need to cast the result of the lookup to the right type. To avoid casting, please use one of following:

1. findByName(String, Class)
2. findByName(String, Class, boolean)
3. findByName(Container, String, Class)
4. findByName(Container, String, Class, boolean)

Parameters:

name - the name of the component to find.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

Robot.settings(), Settings.componentLookupScope(), ComponentLookupScope

findByName

@Nonnull
<T extends Component> T findByName(@Nullable
                                         String name,
                                         @Nonnull
                                         Class<T> type)

Finds an AWT or Swing Component by name and type. If this finder is attached to a Robot , it will use the component lookup scope in the Robot's Settings to determine whether the component to find should be showing or not. If this finder is not attached to any Robot, the component to find does not have to be showing.

Parameters:

name - the name of the component to find.

type - the type of the component to find.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

Robot.settings(), Settings.componentLookupScope(), ComponentLookupScope, findByName(String)

findByName

@Nonnull
<T extends Component> T findByName(@Nullable
                                         String name,
                                         @Nonnull
                                         Class<T> type,
                                         boolean showing)

Finds an AWT or Swing Component by name and type.

Parameters:

name - the name of the component to find.

type - the type of the component to find.

showing - indicates whether the component to find should be visible (or showing) or not.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByName(String)

findByName

@Nonnull
Component findByName(@Nullable
                           String name,
                           boolean showing)

Finds an AWT or Swing Component by name.

Parameters:

name - the name of the component to find.

showing - indicates whether the component to find should be visible (or showing) or not.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByName(String)

findByName

@Nonnull
Component findByName(@Nonnull
                           Container root,
                           @Nullable
                           String name)

Finds an AWT or Swing Component by name, in the hierarchy under the given root. If this finder is attached to a Robot, it will use the component lookup scope in the Robot's Settings to determine whether the component to find should be showing or not. If this finder is not attached to any Robot, the component to find does not have to be showing.

Parameters:

root - the root used as the starting point of the search.

name - the name of the component to find.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

Robot.settings(), Settings.componentLookupScope(), ComponentLookupScope, findByName(String)

findByName

@Nonnull
Component findByName(@Nonnull
                           Container root,
                           @Nullable
                           String name,
                           boolean showing)

Finds an AWT or Swing Component by name, in the hierarchy under the given root.

Parameters:

root - the root used as the starting point of the search.

name - the name of the component to find.

showing - indicates whether the component to find should be visible (or showing) or not.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByName(String)

findByName

@Nonnull
<T extends Component> T findByName(@Nonnull
                                         Container root,
                                         @Nullable
                                         String name,
                                         @Nonnull
                                         Class<T> type)

Finds an AWT or Swing Component by name and type, in the hierarchy under the given root. If this finder is attached to a Robot, it will use the component lookup scope in the Robot's Settings to determine whether the component to find should be showing or not. If this finder is not attached to any Robot, the component to find does not have to be showing.

Parameters:

root - the root used as the starting point of the search.

name - the name of the component to find.

type - the type of the component to find.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

Robot.settings(), Settings.componentLookupScope(), ComponentLookupScope, findByName(String)

findByName

@Nonnull
<T extends Component> T findByName(@Nonnull
                                         Container root,
                                         @Nullable
                                         String name,
                                         @Nonnull
                                         Class<T> type,
                                         boolean showing)

Finds an AWT or Swing Component by name and type, in the hierarchy under the given root.

Parameters:

root - the root used as the starting point of the search.

name - the name of the component to find.

type - the type of the component to find.

showing - indicates whether the component to find should be visible (or showing) or not.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

See Also:

findByName(String)

find

@Nonnull
Component find(@Nonnull
                     ComponentMatcher m)

Finds an AWT or Swing Component using the given ComponentMatcher. The given matcher will be evaluated in the event dispatch thread (EDT.) Implementations of ComponentMatcher do not need to be concerned about the event dispatch thread (EDT.)

Parameters:

m - the matcher to use to find the component of interest.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

find

@Nonnull
<T extends Component> T find(@Nonnull
                                   GenericTypeMatcher<T> m)

Finds an AWT or Swing Component using the given GenericTypeMatcher. The given matcher will be evaluated in the event dispatch thread (EDT.) Implementations of GenericTypeMatcher do not need to be concerned about the event dispatch thread (EDT.)

Parameters:

m - the matcher to use to find the component of interest.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

find

@Nonnull
<T extends Component> T find(@Nonnull
                                   Container root,
                                   @Nonnull
                                   GenericTypeMatcher<T> m)

Finds an AWT or Swing Component using the given GenericTypeMatcher in the hierarchy under the given root. The given matcher will be evaluated in the event dispatch thread (EDT.) Implementations of GenericTypeMatcher do not need to be concerned about the event dispatch thread (EDT.)

Parameters:

root - the root used as the starting point of the search.

m - the matcher to use to find the component.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

find

@Nonnull
Component find(@Nullable
                     Container root,
                     @Nonnull
                     ComponentMatcher m)

Finds an AWT or Swing Component using the given ComponentMatcher in the hierarchy under the given root. The given matcher will be evaluated in the event dispatch thread (EDT.) Implementations of ComponentMatcher do not need to be concerned about the event dispatch thread (EDT.)

Parameters:

root - the root used as the starting point of the search.

m - the matcher to use to find the component.

Returns:

the found component.

Throws:

ComponentLookupException - if a matching component could not be found.

ComponentLookupException - if more than one matching component is found.

findAll

@Nonnull
Collection<Component> findAll(@Nonnull
                                    ComponentMatcher m)

Returns all the AWT or Swing Components that match the search criteria specified in the given ComponentMatcher.

Parameters:

m - the matcher to use to find the component.

Returns:

all the Components that match the search criteria specified in the given ComponentMatcher; or an empty collection, if there are no matching components.

findAll

@Nonnull
Collection<Component> findAll(@Nonnull
                                    Container root,
                                    @Nonnull
                                    ComponentMatcher m)

Returns all the AWT or Swing Components under the given root that match the search criteria specified in the given ComponentMatcher.

Parameters:

root - the root used as the starting point of the search.

m - the matcher to use to find the component.

Returns:

all the Components under the given root that match the search criteria specified in the given ComponentMatcher; or an empty collection, if there are no matching components.

findAll

@Nonnull
<T extends Component> Collection<T> findAll(@Nonnull
                                                  GenericTypeMatcher<T> m)

Returns all the AWT or Swing Components that match the search criteria specified in the given GenericTypeMatcher.

Parameters:

m - the matcher to use to find the component.

Returns:

all the Components that match the search criteria specified in the given GenericTypeMatcher ; or an empty collection, if there are no matching components.

findAll

@Nonnull
<T extends Component> Collection<T> findAll(@Nonnull
                                                  Container root,
                                                  @Nonnull
                                                  GenericTypeMatcher<T> m)

Returns all the AWT or Swing Components under the given root that match the search criteria specified in the given GenericTypeMatcher.

Parameters:

root - the root used as the starting point of the search.

m - the matcher to use to find the component.

Returns:

all the Components under the given root that match the search criteria specified in the given GenericTypeMatcher; or an empty collection, if there are no matching components.

includeHierarchyIfComponentNotFound

boolean includeHierarchyIfComponentNotFound()

Returns whether the message in a ComponentLookupException should include the current component hierarchy. The default value is true.

Returns:

true if the component hierarchy is included as part of the ComponentLookupException message, false otherwise.

includeHierarchyIfComponentNotFound

void includeHierarchyIfComponentNotFound(boolean newValue)

Updates whether the message in a ComponentLookupException should include the current component hierarchy. The default value is true.

Parameters:

newValue - the new value to set.