com.iplanet.jato.view.html
Class CheckBox

java.lang.Object
  |
  +--com.iplanet.jato.view.ViewBase
        |
        +--com.iplanet.jato.view.DisplayFieldImpl
              |
              +--com.iplanet.jato.view.html.HtmlDisplayFieldBase
                    |
                    +--com.iplanet.jato.view.html.CheckBox
All Implemented Interfaces:
BooleanDisplayField, DisplayField, HtmlDisplayField, View

public class CheckBox
extends HtmlDisplayFieldBase
implements BooleanDisplayField

The CheckBox class encapsulates and implements the server-side representation of an HTML check box statement.

The API has been designed to favor the boolean nature of a check box. It is generally recommended that clients use the boolean accessor/mutator (isChecked() and setChecked(boolean)) whenever possible as opposed to the object based accessor/mutators ( getValue(), setValue(Object) ).

Notes on the distinction between value, checked value and unchecked value

Each checkbox may define a checked value and an unchecked value. For example, assume that the checkbox creator has designated that the checked value be "T" and the unchecked value be "F". These assignments are made via the setCheckedValue(Object) and setUncheckedValue(Object) methods. The actual values are arbitrary.

The checked value is the value that is encoded into the checkbox's HTML string. This is the value that is returned as a request parameter when an HTML form is submitted with a checked checkbox.

e.g. for a sample checkbox html The checked value in this example is "T"

The unchecked value in this example not evident in the HTML. There is no HTML provision for embedding an unchecked value in the HTML. In fact, unchecked checkboxes are not returned as request parameters at all. The server has to infer the unchecked value based on the absence of a given checkbox from the request parameter list.

The display field "value", distinct from the checked value and unchecked value, is the value that is stored in this display field's bound model. This is behavior consistent with all display fields.

This checkbox implementation has been careful to ensure that the field "value" is set to either the checked value or unchecked value. The only exception is for a Boolean object which might be mapped into the model directly via a data retrieval. In that case this implementation, will evaluate the Boolean.booleanValue() and map it to the corresponding checked state or unchecked state.

Version:
JATO/1.2.2 $Id: CheckBox.java,v 1.11 2002/03/16 03:26:44 todd Exp $

Fields inherited from interface com.iplanet.jato.view.View
QUALIFIED_VIEW_NAME_SEPARATOR
 
Fields inherited from interface com.iplanet.jato.view.html.HtmlDisplayField
QBE_CONTROL_NAME_SUFFIX
 
Constructor Summary
CheckBox(ContainerView parent, java.lang.String name, java.lang.Object checkedValue, java.lang.Object uncheckedValue, boolean checked)
          Construct a minimal instance using the parent's default model and the field's name as its bound name
CheckBox(View parent, Model model, java.lang.String name, java.lang.Object checkedValue, java.lang.Object uncheckedValue, boolean checked)
          Construct a minimal instance using the parent's default model and the field's name as its bound name
CheckBox(View parent, Model model, java.lang.String name, java.lang.String boundName, java.lang.Object checkedValue, java.lang.Object uncheckedValue, boolean checked, DisplayFieldDescriptor descriptor)
          This constructor can be used when creating a CheckBox directly
 
Method Summary
 boolean booleanValue()
          Returns the boolean state of the field derived from the current value.
 java.lang.Object getCheckedValue()
          Returns the value that has been designated as the "checked value" This is the value that is encoded into the checkbox's HTML string.
 java.lang.Object getFalseValue()
          Same as getUncheckedValue()
 java.lang.Object getTrueValue()
          Same as getCheckedValue()
 java.lang.Object getUncheckedValue()
          Returns the value that has been designated as the "unchecked value" Contrary to the checked value, the unchecked value is NOT encoded in the checkbox's HTML string, since there is no HTML attribute.
 java.lang.Object getValue()
          This version will defensively check to see if the model value is a Boolean object.
 boolean isChecked()
          Returns true if the current display field value is equal to the the checked value.
 void setChecked(boolean value)
          Checks or unchecks the check box
 void setCheckedValue(java.lang.Object value)
          Sets the value to be associated with the checked state.
 void setUncheckedValue(java.lang.Object value)
          Sets the value to be associated with the unchecked state.
 void setValue(java.lang.Object value)
          Sets the check box value.
 void setValue(java.lang.Object value, boolean overwrite)
          Sets the check box value
 
Methods inherited from class com.iplanet.jato.view.html.HtmlDisplayFieldBase
getExtraHtml, getQBEControlQualifiedName, setExtraHtml, urlEncodedValue
 
Methods inherited from class com.iplanet.jato.view.DisplayFieldImpl
getBoundName, getDescriptor, getModel, getValues, setBoundName, setDescriptor, setModel, setValues, setValues, stringValue
 
Methods inherited from class com.iplanet.jato.view.ViewBase
getName, getParent, getParentViewBean, getQualifiedName, getRootView, getRootView, setName, setParent
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.iplanet.jato.view.DisplayField
getDescriptor, getValues, setValues, stringValue
 
Methods inherited from interface com.iplanet.jato.view.View
getName, getParent, getQualifiedName, setParent
 

Constructor Detail

CheckBox

public CheckBox(ContainerView parent,
                java.lang.String name,
                java.lang.Object checkedValue,
                java.lang.Object uncheckedValue,
                boolean checked)
Construct a minimal instance using the parent's default model and the field's name as its bound name
Parameters:
parent - The parent view of this object
name - This view's name and model bound name
checkedValue - The value that will be associated with a selected check box
uncheckedValue - The value that will be associated with an unselected check box
checked - if true, this field's value is set to its true value if false, this field's value is set to its false value

CheckBox

public CheckBox(View parent,
                Model model,
                java.lang.String name,
                java.lang.Object checkedValue,
                java.lang.Object uncheckedValue,
                boolean checked)
Construct a minimal instance using the parent's default model and the field's name as its bound name
Parameters:
parent - The parent view of this object
model - The model to which this DisplayField is bound
name - This view's name and model bound name
checkedValue - The value that will be associated with a selected check box
uncheckedValue - The value that will be associated with an unselected check box
checked - if true, this field's value is set to its true value if false, this field's value is set to its false value

CheckBox

public CheckBox(View parent,
                Model model,
                java.lang.String name,
                java.lang.String boundName,
                java.lang.Object checkedValue,
                java.lang.Object uncheckedValue,
                boolean checked,
                DisplayFieldDescriptor descriptor)
This constructor can be used when creating a CheckBox directly
Parameters:
parent - The parent view of this object
model - The model to which this DisplayField is bound
name - This view's name.
boundName - The name of the model field to which this DisplayField is bound
checkedValue - The value that will be associated with a selected check box
uncheckedValue - The value that will be associated with an unselected check box
checked - if true, this field's value is set to its true value if false, this field's value is set to its false value
descriptor - This DisplayField's DisplayFieldDescriptor. May be null.
Method Detail

isChecked

public boolean isChecked()
Returns true if the current display field value is equal to the the checked value.
Returns:
true if checked, false if unchecked
See Also:
booleanValue()

setChecked

public void setChecked(boolean value)
Checks or unchecks the check box
Parameters:
value - if true then field is checked, otherwise field is unchecked

setValue

public void setValue(java.lang.Object value)
Sets the check box value. Same as setValue(value, true);
Specified by:
setValue in interface DisplayField
Overrides:
setValue in class DisplayFieldImpl
Parameters:
value - The value is compared to this fields "checked value" and "unchecked value". If the value matches either of these legal values, then the field value is adjusted. Otherwise an IllegalArgumentException will be thrown
Throws:
java.lang.IllegalArgumentException - Thrown if the incoming value does not match either the checked value or the unchecked value.

setValue

public void setValue(java.lang.Object value,
                     boolean overwrite)
Sets the check box value
Overrides:
setValue in class DisplayFieldImpl
Parameters:
value - The value is compared to this fields "checked value" and "unchecked value". If the value matches either of these legal values, then the field value is adjusted. Otherwise an IllegalArgumentException will be thrown
overwrite - specifies whether to overwrite an already existing value
Throws:
java.lang.IllegalArgumentException - Thrown if the incoming value does not match either the checked value or the unchecked value.

getValue

public java.lang.Object getValue()
This version will defensively check to see if the model value is a Boolean object.

If the model value is a Boolean then this method will return the field's checkedValue or uncheckedValue according to the Boolean state.

If the model value is not a Boolean value then this method will simple return the raw model value.

Specified by:
getValue in interface DisplayField
Overrides:
getValue in class DisplayFieldImpl
Returns:
the current value

getCheckedValue

public java.lang.Object getCheckedValue()
Returns the value that has been designated as the "checked value" This is the value that is encoded into the checkbox's HTML string. e.g. for a sample checkbox html.

See class description for details on relation between value, checked value and unchecked value.

Returns:
the value associated with a checked box
See Also:
getTrueValue()

setCheckedValue

public void setCheckedValue(java.lang.Object value)
Sets the value to be associated with the checked state.

See class description for details on relation between value, checked value and unchecked value.

Parameters:
value - The checked value

getUncheckedValue

public java.lang.Object getUncheckedValue()
Returns the value that has been designated as the "unchecked value" Contrary to the checked value, the unchecked value is NOT encoded in the checkbox's HTML string, since there is no HTML attribute.

See class description for details on relation between value, checked value and unchecked value.

Returns:
the value associated with a checked box
See Also:
getFalseValue()

setUncheckedValue

public void setUncheckedValue(java.lang.Object value)
Sets the value to be associated with the unchecked state.

See class description for details on relation between value, checked value and unchecked value.

Parameters:
value - The unchecked value

booleanValue

public boolean booleanValue()
Returns the boolean state of the field derived from the current value. Generally, if the current value available from DisplayField.getValue() matches the value of getTrueValue(), this method will return true.
Specified by:
booleanValue in interface BooleanDisplayField
See Also:
isChecked()

getTrueValue

public java.lang.Object getTrueValue()
Same as getCheckedValue()
Specified by:
getTrueValue in interface BooleanDisplayField
See Also:
getCheckedValue()

getFalseValue

public java.lang.Object getFalseValue()
Same as getUncheckedValue()
Specified by:
getFalseValue in interface BooleanDisplayField
See Also:
getUncheckedValue()