public class ValidationGroup extends ValidationItem
ValidationGroup
logically groups a set of GUI-components,
such as text fields, lists, tables, comboboxes etc, each validated
by one or more validators (such as the built-in ones provided by
the framework in StringValidators
).
Note: If you are validating Swing components, you will probably
want to use SwingValidationGroup
which contains
convenience add methods for common Swing components, and performs
Swing-specific threading correctness checks.
A ValidationGroup
is typically associated with a panel
containing GUI-components (such as a JPanel
or JDialog
in Swing). The idea with logically grouping GUI-components
(as opposed to treating them completely separately) is to to
indicate the most severe Problem
in the panel (graded
by Severity
) -- the "lead
problem" of the group -- to the user in various ways. Even if the
user happens to currently be interacting with another GUI component
that has no error in it, the lead problem of the panel/group will
be visible to the user.
If there is more than one Problem that is the most severe (they have equal Severity) in the group of UI-components, then the one in the UI-component that has been most recently interacted with will be the lead problem.
The way for the ValidationGroup
to show the lead
problem in the UI is by using one or more instances of the ValidationUI
interface. ValidationUI
instances can be
added by client code using the addUI(org.netbeans.validation.api.ui.ValidationUI)
method.
One ValidationUI
instance could indicate the lead
problem for example by showing a message in some status
bar. Another one could disable some OK-button (which could be
suitable if the lead problems has Severity.FATAL
) etc. All
these ValidationUI
s are updated whenever the lead problem
of the group changes.
If the ValidationGroup contains UI-components whose validity
depends not only on their own state but on the state of each other
as well, they can be said to have validity interdependencies. In
such cases not only the state of each component needs to be
validated, but the combination of components as well. This is done
by passing a GroupValidator
object when creating the
ValidationGroup. For more on that, see GroupValidator
.
Now, to add a GUI-component to the ValidationGroup
,
client code would wrap it (together with the desired Validators)
into a ValidationListener
that is then added to the ValidationGroup
using the addItem(org.netbeans.validation.api.ui.ValidationItem, boolean)
method. Note
that this is the generic but perhaps inconvenient case -- the
subclass SwingValidationGroup
contains
a number of add
-methods for convenience, to simplify this
procedure for common Swing components.
Each ValidationListener
listens to suitable GUI-events
(often key-press events or mouse-events). When such an event occurs
the ValidationListener
will perform revalidation and then
notify its parent ValidationGroup
so that it can reevaluate
its lead problem.
Not only ValidationListener:s can be added to ValidationGroup,
but so can other ValdiationGroups as well. (This is the reason why
ValidationListener and ValidationGroup share a common superclass,
ValidationItem
, and that this is the type of the argument
of ValidationGroup#add
.) This is useful when there are two
separate panels with their own ValidationGroup
s, and one of
the panels is (perhaps temporarily) to be embedded into the other.
Whenever there is a change in one of the added child
ValidationGroup's components, it will drive the UI(s) belonging to
the parent group, as well as (optionally) its own. (The latter can
be disabled by passing true
as second parameter to addItem(org.netbeans.validation.api.ui.ValidationItem, boolean)
instead of false
The core functionality of the ValidationGroup
with
added ValidationItem
:s works as follows:
ValidationListener
will observe that and make sure the component
is validated (by invoking the Validator
(s)) and then
decorate the UI component if there is a Problem in it. This is
unless the ValidationListener is suspended, in which case nothing
at all will happen, see ValidationItem.runWithValidationSuspended(java.lang.Runnable)
Problem
in that
UI component, then this will also become the lead problem of the
whole group because it is the most recent of the most severe
problems in the groups.showProblem
method of the
ValidationUI
:s of the group will be called. This may
for example involve disabling an OK-button if the lead problem is
fatal (and enabling it if not) and showing an error message. This
is unless this ValidationGroup has been added "with disabled UI" to
another ValidationGroup, in which case the Problem will not be
shown in the ValidationUI. Modifier | Constructor and Description |
---|---|
protected |
ValidationGroup(GroupValidator additionalGroupValidation,
ValidationUI... ui) |
protected |
ValidationGroup(ValidationUI... ui) |
Modifier and Type | Method and Description |
---|---|
<ComponentType,ValueType> |
add(ComponentType comp,
Validator<ValueType>... validators) |
<ComponentType,ValueType> |
add(ComponentType comp,
Validator<ValueType> validator) |
void |
addItem(ValidationItem validationItem,
boolean disableUI)
Adds a ValidationItem (i.e a ValidationListener or another
ValidationGroup) to this ValidationGroup.
|
void |
addUI(ValidationUI ui)
Add a UI which should be called on validation of this group or
any components within it.
|
static ValidationGroup |
create(GroupValidator additionalGroupValidation,
ValidationUI... ui)
Create a new validation group
|
static ValidationGroup |
create(ValidationUI... ui)
Create a new validation group
|
protected <T> ValidationUI |
decorationFor(T component) |
void |
remove(ValidationItem validationItem)
Removes a previously added ValidationItem (i.e a
ValidationListener or another ValidationGroup) to this
ValidationGroup.
|
void |
removeUI(ValidationUI ui)
Remove a delegate UI which is being controlled by this
validation item.
|
performValidation, runWithValidationSuspended
protected ValidationGroup(GroupValidator additionalGroupValidation, ValidationUI... ui)
protected ValidationGroup(ValidationUI... ui)
public static ValidationGroup create(ValidationUI... ui)
ui
- Zero or more initial UIs which will display errorspublic static ValidationGroup create(GroupValidator additionalGroupValidation, ValidationUI... ui)
additionalGroupValidation
- ui
- Zero or more initial UIs which will display errorspublic final <ComponentType,ValueType> void add(ComponentType comp, Validator<ValueType>... validators)
ComponentType
- ValueType
- comp
- validators
- public final <ComponentType,ValueType> void add(ComponentType comp, Validator<ValueType> validator)
ComponentType
- ValueType
- comp
- validator
- protected <T> ValidationUI decorationFor(T component)
public final void addUI(ValidationUI ui)
ui
- An implementation of ValidationUIpublic final void removeUI(ValidationUI ui)
ui
- The UIpublic final void addItem(ValidationItem validationItem, boolean disableUI)
The purpose of being able to disable a ValidationUI is so you can compose together reusable panels which have their own ValidationUI, but only let the outer ValidationUI show the lead problem when one is inside another. Typically, without the ability to turn off the inner panel's ValidationUI, when there's a problem in the inner panel the error message is going to be shown twice -- once at the bottom of the dialog and one in the middle of the screen inside the inner panel -- which would look bad.
Note that the subclass SwingValidationGroup
contains a number of add
-methods for convenience, to
simplify this procedure for common Swing components
validationItem
- item to adddisableUI
- indicates that the validation UI of the parent panel
should not be notifiedpublic final void remove(ValidationItem validationItem)
If the ValidationItem to be removed has the current lead problem of the ValidationGroup, the ValidationGroup will remove that and evaluate a new lead problem
validationItem
- item to remove