com.jgoodies.validation.view
Class ValidationComponentUtils

java.lang.Object
  extended by com.jgoodies.validation.view.ValidationComponentUtils

public final class ValidationComponentUtils
extends Object

Consists exclusively of static methods that provide convenience behavior for operating on components that present validation data. Methods that access component state utilize the JComponent client property mechanism as a backing store.

Version:
$Revision: 1.20 $
Author:
Karsten Lentzsch
See Also:
ValidationMessage, ValidationMessage.key(), ValidationResult, ValidationResult.subResult(Object), ValidationResult.keyMap()

Nested Class Summary
static interface ValidationComponentUtils.Visitor
          Describes visitors that visit a component tree.
 
Method Summary
static ValidationResult getAssociatedResult(JComponent comp, Map<Object,ValidationResult> keyMap)
          Returns the ValidationResult associated with the given component using the specified validation result key map, or null if the component has no message key set, or ValidationResult.EMPTY if the key map contains no result for the component.
static Color getErrorBackground()
          Returns the error background color used to mark components that have an associated validation error.
static Object getInputHint(JComponent comp)
          Returns the component's input hint that is stored in a client property.
static Color getMandatoryBackground()
          Returns a default background color that can be used as the component background for components with mandatory content.
static Border getMandatoryBorder()
          Lazily creates and returns a Border instance that is used to indicate that a component's content is mandatory.
static Color getMandatoryForeground()
          Returns a default foreground color that can be used as the component foreground for components with mandatory content.
static Object[] getMessageKeys(JComponent comp)
          Returns the message key that has been set to associate the given component with a set of ValidationMessages.
static Severity getSeverity(JComponent comp)
          Returns the component's Severity if it has been set before.
static Color getWarningBackground()
          Returns the warning background color used to mark components that have an associated validation warning.
static boolean hasError(JComponent comp, ValidationResult result)
          Checks and answers if the specified component is associated with an error message in the given validation result.
static boolean hasWarning(JComponent comp, ValidationResult result)
          Checks and answers if the specified component is associated with a warning message in the given validation result.
static boolean isMandatory(JComponent comp)
          Returns if the component has been marked as mandatory.
static boolean isMandatoryAndBlank(JComponent comp)
          Returns if the component is a JTextComponent with blank content and has been marked as mandatory.
static void setErrorBackground(JTextComponent comp)
          Sets the text component's background to a color that shall indicate that the component's content has is invalid with error severity.
static void setInputHint(JComponent comp, Object hint)
          Sets the input hint for the given component.
static void setMandatory(JComponent comp, boolean mandatory)
          Marks the given component as mandatory or optional.
static void setMandatoryBackground(JTextComponent comp)
          Sets the text component's background to a color that shall indicate that the component's content is mandatory.
static void setMandatoryBorder(JTextComponent comp)
          Sets the text component's border to use a new border that shall indicate that the component's content is mandatory.
static void setMessageKey(JComponent comp, Object messageKey)
          Associates the given component with the specified message key.
static void setMessageKeys(JComponent comp, Object... messageKeys)
          Associates the given component with the specified message keys.
static void setSeverity(JComponent comp, Severity severity)
          Marks the given component with the specified severity.
static void setWarningBackground(JTextComponent comp)
          Sets the text component's background to a color that shall indicate that the component's content is invalid with warning severity.
static void updateComponentTreeMandatoryAndBlankBackground(Container container)
          Traverses a component tree and sets mandatory backgrounds to text components that have blank content and have been marked as mandatory with setMandatory(JComponent, boolean) before.
static void updateComponentTreeMandatoryBackground(Container container)
          Traverses a component tree and sets mandatory backgrounds to text components that have been marked as mandatory with setMandatory(JComponent, boolean) before.
static void updateComponentTreeMandatoryBorder(Container container)
          Traverses a component tree and sets mandatory borders to text components that have been marked as mandatory with setMandatory(JComponent, boolean) before.
static void updateComponentTreeSeverity(Container container, ValidationResult result)
          Traverses a component tree and sets the severity for all text components.
static void updateComponentTreeSeverityBackground(Container container, ValidationResult result)
          Traverses a component tree and sets the text component backgrounds according to the severity of an associated validation result - if any.
static void visitComponentTree(Container container, Map<Object,ValidationResult> keyMap, ValidationComponentUtils.Visitor visitor)
          Traverses the component tree starting at the given container and invokes the given visitor's #visit method on each instance of JTextComponent.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

isMandatory

public static boolean isMandatory(JComponent comp)
Returns if the component has been marked as mandatory.

Parameters:
comp - the component to be checked
Returns:
true if the component has been marked as mandatory
See Also:
isMandatoryAndBlank(JComponent), setMandatory(JComponent, boolean), setMandatoryBackground(JTextComponent), setMandatoryBorder(JTextComponent)

isMandatoryAndBlank

public static boolean isMandatoryAndBlank(JComponent comp)
Returns if the component is a JTextComponent with blank content and has been marked as mandatory.

Parameters:
comp - the component to be checked
Returns:
true if the component's has a blank content and has been marked as mandatory
See Also:
isMandatory(JComponent), setMandatory(JComponent, boolean), setMandatoryBackground(JTextComponent), setMandatoryBorder(JTextComponent)

setMandatory

public static void setMandatory(JComponent comp,
                                boolean mandatory)
Marks the given component as mandatory or optional. The value will be stored as a client property value.

Parameters:
comp - the component to be marked
mandatory - true for mandatory, false for optional
See Also:
isMandatory(JComponent), isMandatoryAndBlank(JComponent), setMandatoryBackground(JTextComponent), setMandatoryBorder(JTextComponent)

getSeverity

public static Severity getSeverity(JComponent comp)
Returns the component's Severity if it has been set before. Useful for validation-aware containers that render the component's validation state.

Parameters:
comp - the component to be read
Returns:
the component's Severity as set before
See Also:
setSeverity(JComponent, Severity), updateComponentTreeSeverity(Container, ValidationResult), updateComponentTreeSeverityBackground(Container, ValidationResult)

setSeverity

public static void setSeverity(JComponent comp,
                               Severity severity)
Marks the given component with the specified severity. The severity will be stored as a client property value. Useful for validation-aware containers that render the component's validation state once it has been set.

Parameters:
comp - the component that shall be marked
severity - the component's severity
See Also:
getSeverity(JComponent), updateComponentTreeSeverity(Container, ValidationResult), updateComponentTreeSeverityBackground(Container, ValidationResult)

getMessageKeys

public static Object[] getMessageKeys(JComponent comp)
Returns the message key that has been set to associate the given component with a set of ValidationMessages.

Parameters:
comp - the component to be requested
Returns:
the component's validation association key
See Also:
setMessageKey(JComponent, Object), ValidationMessage, ValidationMessage.key(), ValidationResult.subResult(Object), ValidationResult.keyMap()

setMessageKey

public static void setMessageKey(JComponent comp,
                                 Object messageKey)
Associates the given component with the specified message key. That in turn will associate the component with all ValidationMessages that share this key. The latter can be checked by comparing this key with the key provided by a ValidationMessage.

Parameters:
comp - the component that shall be associated with the key
messageKey - the key to be set
See Also:
getMessageKeys(JComponent), ValidationMessage, ValidationMessage.key(), ValidationResult.subResult(Object), ValidationResult.keyMap()

setMessageKeys

public static void setMessageKeys(JComponent comp,
                                  Object... messageKeys)
Associates the given component with the specified message keys. That in turn will associate the component with all ValidationMessages that share these keys. The latter can be checked by comparing the given (and stored) keys with the key provided by a ValidationMessage.

Since version 2.0.1 this method uses varargs instead of an Object array.

Parameters:
comp - the component that shall be associated with the keys
messageKeys - the keys to be set
Since:
1.4
See Also:
getMessageKeys(JComponent), ValidationMessage, ValidationMessage.key(), ValidationResult.subResult(Object), ValidationResult.keyMap()

getInputHint

public static Object getInputHint(JComponent comp)
Returns the component's input hint that is stored in a client property. Useful to indicate the format of valid data to the user. The input hint object can be a plain String or a compound object, for example that is able to localize the input hint for the active Locale.

To make use of this information an editor should register a listener with the focus management. Whenever the focused component changes, the mechanism can request the input hint for the focus owner using this service and can display the result hint in the user interface.

Parameters:
comp - the component to be requested
Returns:
the component's input hint
See Also:
setInputHint(JComponent, Object)

setInputHint

public static void setInputHint(JComponent comp,
                                Object hint)
Sets the input hint for the given component. This hint can be later retrieved to indicate to the user the format of valid data for the focused component.

Parameters:
comp - the component to set a hint for
hint - the input hint to be associated with the component
See Also:
getInputHint(JComponent)

hasError

public static boolean hasError(JComponent comp,
                               ValidationResult result)
Checks and answers if the specified component is associated with an error message in the given validation result. As a prerequisite, the component must have an association key set. That can be done using setMessageKey(JComponent, Object) or setMessageKeys(JComponent, Object[]).

Note: This method may become slow if invoked for larger validation results and multiple components. In this case, it is recommended to use ValidationResult.keyMap() instead. The latter iterates once over the validation result and can be used later to request the severity for multiple components in almost linear time.

Parameters:
comp - used to get the association key from
result - used to lookup the validation messages from
Returns:
true if the given component is associated with an error message
Throws:
NullPointerException - if the component or validation result is null
See Also:
hasWarning(JComponent, ValidationResult), getMessageKeys(JComponent)

hasWarning

public static boolean hasWarning(JComponent comp,
                                 ValidationResult result)
Checks and answers if the specified component is associated with a warning message in the given validation result. As a prerequisite, the component must have a message key set. That can be done using setMessageKey(JComponent, Object) or setMessageKeys(JComponent, Object[]).

Note: This method may become slow if invoked for larger validation results and multiple components. In this case, it is recommended to use ValidationResult.keyMap() instead. The latter iterates once over the validation result and can be used later to request the severity for multiple components in almost linear time.

Parameters:
comp - used to get the association key from
result - used to lookup the validation messages from
Returns:
true if the given component is associated with a warning message
Throws:
NullPointerException - if the component or validation result is null
See Also:
hasError(JComponent, ValidationResult), getMessageKeys(JComponent)

getMandatoryBackground

public static Color getMandatoryBackground()
Returns a default background color that can be used as the component background for components with mandatory content. Typically this color will be used with instances of JTextComponent.

Note: The component background colors are managed by the look&feel implementation. Many l&fs will honor a custom background color. However, some l&fs may ignore custom background colors. It is recommended to check the appearance in all l&fs available in an application.

Returns:
a background color useful for components with mandatory content
See Also:
getMandatoryForeground()

getMandatoryForeground

public static Color getMandatoryForeground()
Returns a default foreground color that can be used as the component foreground for components with mandatory content. Typically this color will be used with instances of JTextComponent.

Note: The component foreground and border colors are managed by the look&feel implementation. Many l&fs will honor a custom foreground color and custom border configuration. However, some l&fs may ignore these custom settings. It is recommended to check the appearance in all l&fs available in an application.

Returns:
a foreground color useful for components with mandatory content
See Also:
getMandatoryBackground(), getMandatoryBorder()

setMandatoryBackground

public static void setMandatoryBackground(JTextComponent comp)
Sets the text component's background to a color that shall indicate that the component's content is mandatory.

Note: The component background colors are managed by the look&feel implementation. Many l&fs will honor a custom foreground color and custom border configuration. However, some l&fs may ignore these custom settings. It is recommended to check the appearance in all l&fs available in an application.

Parameters:
comp - the text component that shall get a new background
See Also:
setMandatoryBorder(JTextComponent), setErrorBackground(JTextComponent), setWarningBackground(JTextComponent)

getErrorBackground

public static Color getErrorBackground()
Returns the error background color used to mark components that have an associated validation error.

Returns:
the error background color
Since:
1.0.2
See Also:
getWarningBackground(), setErrorBackground(JTextComponent), updateComponentTreeSeverityBackground(Container, ValidationResult)

setErrorBackground

public static void setErrorBackground(JTextComponent comp)
Sets the text component's background to a color that shall indicate that the component's content has is invalid with error severity.

Note: The component background colors are managed by the look&feel implementation. Many l&fs will honor a custom foreground color and custom border configuration. However, some l&fs may ignore these custom settings. It is recommended to check the appearance in all l&fs available in an application.

Parameters:
comp - the text component that shall get a new background
See Also:
setMandatoryBackground(JTextComponent), setWarningBackground(JTextComponent)

getWarningBackground

public static Color getWarningBackground()
Returns the warning background color used to mark components that have an associated validation warning.

Returns:
the warning background color
Since:
1.0.2
See Also:
getErrorBackground(), setWarningBackground(JTextComponent), updateComponentTreeSeverityBackground(Container, ValidationResult)

setWarningBackground

public static void setWarningBackground(JTextComponent comp)
Sets the text component's background to a color that shall indicate that the component's content is invalid with warning severity.

Note: The component background colors are managed by the look&feel implementation. Many l&fs will honor a custom foreground color and custom border configuration. However, some l&fs may ignore these custom settings. It is recommended to check the appearance in all l&fs available in an application.

Parameters:
comp - the text component that shall get a new background
See Also:
setMandatoryBackground(JTextComponent), setErrorBackground(JTextComponent)

setMandatoryBorder

public static void setMandatoryBorder(JTextComponent comp)
Sets the text component's border to use a new border that shall indicate that the component's content is mandatory.

Note: The component foreground and border colors are managed by the look&feel implementation. Many l&fs will honor a custom foreground color and custom border configuration. However, some l&fs may ignore these custom settings. It is recommended to check the appearance in all l&fs available in an application.

Parameters:
comp - the component that gets a new border
See Also:
setMandatoryBackground(JTextComponent), getMandatoryBorder()

getMandatoryBorder

public static Border getMandatoryBorder()
Lazily creates and returns a Border instance that is used to indicate that a component's content is mandatory.

Returns:
a Border that is used to indicate that a component's content is mandatory

updateComponentTreeMandatoryBackground

public static void updateComponentTreeMandatoryBackground(Container container)
Traverses a component tree and sets mandatory backgrounds to text components that have been marked as mandatory with setMandatory(JComponent, boolean) before. The iteration starts at the given container.

Parameters:
container - the component tree root
See Also:
setMandatory(JComponent, boolean), setMandatoryBackground(JTextComponent)

updateComponentTreeMandatoryAndBlankBackground

public static void updateComponentTreeMandatoryAndBlankBackground(Container container)
Traverses a component tree and sets mandatory backgrounds to text components that have blank content and have been marked as mandatory with setMandatory(JComponent, boolean) before. The iteration starts at the given container.

Parameters:
container - the component tree root
See Also:
setMandatory(JComponent, boolean), setMandatoryBackground(JTextComponent)

updateComponentTreeMandatoryBorder

public static void updateComponentTreeMandatoryBorder(Container container)
Traverses a component tree and sets mandatory borders to text components that have been marked as mandatory with setMandatory(JComponent, boolean) before. The iteration starts at the given container.

Parameters:
container - the component tree root
See Also:
setMandatory(JComponent, boolean), setMandatoryBorder(JTextComponent)

updateComponentTreeSeverityBackground

public static void updateComponentTreeSeverityBackground(Container container,
                                                         ValidationResult result)
Traverses a component tree and sets the text component backgrounds according to the severity of an associated validation result - if any. The iteration starts at the given container.

The message keys used to associate components with validation messages should be set using setMessageKey(JComponent, Object) before you call this method.

Parameters:
container - the component tree root
result - the validation result used to lookup the severities
Since:
1.0.2
See Also:
setMandatory(JComponent, boolean), setMessageKey(JComponent, Object), setMandatoryBackground(JTextComponent), setErrorBackground(JTextComponent), setWarningBackground(JTextComponent)

updateComponentTreeSeverity

public static void updateComponentTreeSeverity(Container container,
                                               ValidationResult result)
Traverses a component tree and sets the severity for all text components. The iteration starts at the given container. If a validation result is associated with a component, the result's severity is set. Otherwise the severity is set to null. The severity is set using setSeverity(JComponent, Severity).

Before you use this method, associate components with validation messages using setMessageKey(JComponent, Object).

Parameters:
container - the component tree root
result - the validation result that provides the associated messages
See Also:
setSeverity(JComponent, Severity)

visitComponentTree

public static void visitComponentTree(Container container,
                                      Map<Object,ValidationResult> keyMap,
                                      ValidationComponentUtils.Visitor visitor)
Traverses the component tree starting at the given container and invokes the given visitor's #visit method on each instance of JTextComponent. Useful to perform custom component tree updates that are not already provided by the #updateComponentTreeXXX methods.

The arguments passed to the #visit method are the visited component and its associated validation subresult. This subresult is requested from the specified keyMap using the component's message key.

Before you use this method, associate text component with validation messages using setMessageKey(JComponent, Object).

Parameters:
container - the component tree root
keyMap - maps messages keys to associated validation results
visitor - the visitor that is applied to all text components
See Also:
setMessageKey(JComponent, Object), ValidationComponentUtils.Visitor

getAssociatedResult

public static ValidationResult getAssociatedResult(JComponent comp,
                                                   Map<Object,ValidationResult> keyMap)
Returns the ValidationResult associated with the given component using the specified validation result key map, or null if the component has no message key set, or ValidationResult.EMPTY if the key map contains no result for the component.

Parameters:
comp - the component may be marked with a validation message keys
keyMap - maps validation message keys to ValidationResults
Returns:
the ValidationResult associated with the given component as provided by the specified validation key map or null if the component has no message key set, or ValidationResult.EMPTY if no result is associated with the component
Since:
1.4


Copyright © 2003-2011 JGoodies Karsten Lentzsch. All Rights Reserved.