public abstract class GObjectFilter extends Object
GObject when searching. Note that the methods and fields
in this class are designed specifically to support a natural, readable,
boolean expression "mini-language" for use in describing a single
GObject (or group of GObjects) by its (or their)
properties. As a result, it does violate some conventions regarding
the use of public fields (although note that all here are immutable)
and occasionally even the naming conventions for constants (e.g.,
where). However, breaking these conventions is necessary
in this class in order to support the more natural syntax for filter
expressions, and so was deemed a better design choice.
Client classes that wish to use these filters should add the following static import directive:
import static student.testingsupport.GObjectFilter.ClientImports.*;
Note that the GraphicTestCase class already re-exports the
items defined in the GObjectFilter.ClientImports nested class, so GUI test
cases should not include the static import.
The expressions that you can create with this class are designed to represent "filters" or boolean predicates that can be applied to a GObject, returning true if the GObject "matches" the filter or false if the component does not match.
Often, a filter object is created solely for the purpose of passing
the filter into some other operation, such as a search operation. For
example, the student.GraphicTestCase class provides a
getGObject()
method that takes a filter as a parameter. For the examples below, we
will use getGObject() as the context, specifying each
filter as an argument value in a call to that method.
The basic principles for using this class are as follows:
Never try to create a GObjectFilter object directly. Instead,
always write something that looks like a boolean expression, and
that starts with the operator where:
GRect rect = getGObject(GRect.class, where.locationIs(25, 25));
The basic properties you can check with filters include:
locationIs(), textIs(),
visibilityIs(), filledIs(),
widthIs(), and heightIs(). They are
all used the same way:
GLabel name = getGObject(GLabel.class, where.textIs("name"));
GRect rect = getGObject(JLabel.class, where.locationIs(25, 25));
You can combine filters using logical "and" as necessary:
GRect rect = getGObject(GRect,
where.locationIs(25, 25).and.visibilityIs(true).and.filledIs(true));
You can also use "or":
GRect rect = getGObject(GRect,
where.locationIs(25, 25).or.visibilityIs(true).or.filledIs(true));
Operators like "and" and "or" are interpreted strictly left to right. There is no precedence, because of the way Java interprets dot notation.
GRect rect = getGObject(GRect,
where.locationIs(25, 25).or.visibilityIs(true).and.filledIs(true));
// means ((location = (25, 25) or visibility = true) and filled = true)
// note that the left operator is always evaluated first!
If you want to force a different order of evaluation
than strictly left-to-right, then use parentheses by writing the
appropriate operator as and() or or(). Just
be sure to start the new expression inside the parentheses with
where:
GRect rect = getGObject(GRect.class,
where.locationIs(25, 25).or(where.visibilityIs(true).and.filledIs(true)));
// now means (location = (25, 25) or (visibility = true and filled = true))
// because of the extra parentheses used
Finally, you can even use "not" (logical negation), but it is
called like a method, so parentheses (and thus a leading where)
are always required to make the intended extent of the negation
clear:
GRect rect = getGObject(GRect.class,
where.locationIs(25, 25).and.not(where.visibilityIs(true).or.filledIs(true)));
| Modifier and Type | Class and Description |
|---|---|
class |
GObjectFilter.BinaryOperator
A non-static subclass for binary operators that implicitly
captures the outer filter to which it belongs, using it as
the first/left argument to the operator.
|
static class |
GObjectFilter.ClientImports
This class represents the "where" operator that is used to begin
a filter expression.
|
static class |
GObjectFilter.Operator
This base class represents an operator used to create a query.
|
| Modifier and Type | Field and Description |
|---|---|
GObjectFilter.BinaryOperator |
and
The "and" operator for combining filters, designed to be used in
expressions like
where.nameIs("...").and.enabledIs(true). |
GObjectFilter.BinaryOperator |
or
The "or" operator for combining filters, designed to be used in
expressions like
where.locationIs(25, 25).or.textIs("def"). |
| Modifier | Constructor and Description |
|---|---|
protected |
GObjectFilter(String description)
Creates a new filter object.
|
| Modifier and Type | Method and Description |
|---|---|
GObjectFilter |
and(GObjectFilter otherFilter)
The "and" operator for combining filters, when you want to use
parentheses to group its righthand argument.
|
GObjectFilter |
or(GObjectFilter otherFilter)
The "or" operator for combining filters, when you want to use
parentheses to group its righthand argument.
|
abstract boolean |
test(acm.graphics.GObject gobj)
Evaluate whether a GObject matches this filter.
|
String |
toString()
Get a string representation of this filter.
|
public final GObjectFilter.BinaryOperator and
where.nameIs("...").and.enabledIs(true).
This operator is implemented as a public field so that the simple
.and. notation can be used as a connective between
filters. If you want to use parentheses for grouping to define
the right argument, see and(GObjectFilter) instead.public final GObjectFilter.BinaryOperator or
where.locationIs(25, 25).or.textIs("def").
This operator is implemented as a public field so that the simple
.or. notation can be used as a connective between
filters. If you want to use parentheses for grouping to define
the right argument, see or(GObjectFilter) instead.protected GObjectFilter(String description)
description - A string description of this filter, used in
toString().public String toString()
public final GObjectFilter and(GObjectFilter otherFilter)
where.textIs("abc").and(visibility(true).or.filledIs(true)).
If you wish to use the .and. notation instead, leaving
off the parentheses, see and(GObjectFilter).otherFilter - The second argument to "and".public final GObjectFilter or(GObjectFilter otherFilter)
where.textIs("abc").or(visibilityIs(true).and.filledIs(true)).
If you wish to use the .or. notation instead, leaving
off the parentheses, see or(GObjectFilter).otherFilter - The second argument to "or".public abstract boolean test(acm.graphics.GObject gobj)
gobj - The GObject to check