com.google.gwt.user.client.ui

## Class CheckBox

- java.lang.Object
- - com.google.gwt.user.client.ui.UIObject
  - - com.google.gwt.user.client.ui.Widget
    - - com.google.gwt.user.client.ui.FocusWidget
      - - com.google.gwt.user.client.ui.ButtonBase
        - - com.google.gwt.user.client.ui.CheckBox

All Implemented Interfaces:
  IsEditor<LeafValueEditor<java.lang.Boolean>>, HasAllDragAndDropHandlers, HasAllFocusHandlers, HasAllGestureHandlers, HasAllKeyHandlers, HasAllMouseHandlers, HasAllTouchHandlers, HasBlurHandlers, HasClickHandlers, HasDoubleClickHandlers, HasDragEndHandlers, HasDragEnterHandlers, HasDragHandlers, HasDragLeaveHandlers, HasDragOverHandlers, HasDragStartHandlers, HasDropHandlers, HasFocusHandlers, HasGestureChangeHandlers, HasGestureEndHandlers, HasGestureStartHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasMouseDownHandlers, HasMouseMoveHandlers, HasMouseOutHandlers, HasMouseOverHandlers, HasMouseUpHandlers, HasMouseWheelHandlers, HasTouchCancelHandlers, HasTouchEndHandlers, HasTouchMoveHandlers, HasTouchStartHandlers, HasAttachHandlers, HasValueChangeHandlers<java.lang.Boolean>, HasHandlers, HasDirectionEstimator, HasSafeHtml, EventListener, TakesValue<java.lang.Boolean>, Focusable, HasDirectionalSafeHtml, HasDirectionalText, HasEnabled, HasFocus, HasHTML, HasName, HasText, HasValue<java.lang.Boolean>, HasVisibility, HasWordWrap, IsWidget, SourcesClickEvents, SourcesFocusEvents, SourcesKeyboardEvents, SourcesMouseEvents

Direct Known Subclasses:
  RadioButton

    public class CheckBox
    extends ButtonBase
    implements HasName, HasValue<java.lang.Boolean>, HasWordWrap, HasDirectionalSafeHtml, HasDirectionEstimator, IsEditor<LeafValueEditor<java.lang.Boolean>>

A standard check box widget. This class also serves as a base class for `RadioButton`.

### Built-in Bidi Text Support

This widget is capable of automatically adjusting its direction according to its content. This feature is controlled by `setDirectionEstimator(boolean)` or passing a DirectionEstimator parameter to the constructor, and is off by default.

### CSS Style Rules

.gwt-CheckBox
  the outer element
.gwt-CheckBox-disabled
  applied when Checkbox is disabled

### Example

>     public class CheckBoxExample implements EntryPoint {

>       @Override
>       public void onModuleLoad() {
>         // Make a new check box, and select it by default.
>         CheckBox cb = new CheckBox("Foo");
>         cb.setValue(true);

>         // Hook up a handler to find out when it's clicked.
>         cb.addClickHandler(new ClickHandler() {
>           @Override
>           public void onClick(ClickEvent event) {
>             boolean checked = ((CheckBox) event.getSource()).getValue();
>             Window.alert("It is " + (checked ? "" : "not ") + "checked");
>           }
>         });

>         // Add it to the root panel.
>         RootPanel.get().add(cb);
>       }
>     }

### Nested Class Summary

### Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject

`UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

### Field Summary

Fields
`static DirectionEstimator` `DEFAULT_DIRECTION_ESTIMATOR`
`(package private) DirectionalTextHelper` `directionalTextHelper`
`(package private) InputElement` `inputElem`
`(package private) LabelElement` `labelElem`

### Fields inherited from class com.google.gwt.user.client.ui.Widget

`eventsToSink`

### Fields inherited from class com.google.gwt.user.client.ui.UIObject

`DEBUG_ID_PREFIX, MISSING_ELEMENT_ERROR, SETELEMENT_TWICE_ERROR`

### Constructor Summary

Constructors
`` `CheckBox()` Creates a check box with no label.
`protected` `CheckBox(Element elem)`
`` `CheckBox(SafeHtml label)` Creates a check box with the specified text label.
`` `CheckBox(SafeHtml label, DirectionEstimator directionEstimator)` Creates a check box with the specified text label.
`` `CheckBox(SafeHtml label, HasDirection.Direction dir)` Creates a check box with the specified text label.
`` `CheckBox(java.lang.String label)` Creates a check box with the specified text label.
`` `CheckBox(java.lang.String label, boolean asHTML)` Creates a check box with the specified text label.
`` `CheckBox(java.lang.String label, DirectionEstimator directionEstimator)` Creates a label with the specified text and a default direction estimator.
`` `CheckBox(java.lang.String label, HasDirection.Direction dir)` Creates a check box with the specified text label.

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`HandlerRegistration` `addValueChangeHandler(ValueChangeHandler<java.lang.Boolean> handler)` Adds a `ValueChangeEvent` handler.
`LeafValueEditor<java.lang.Boolean>` `asEditor()` Returns the Editor encapsulated by the view object.
`protected void` `ensureDomEventHandlers()`
`DirectionEstimator` `getDirectionEstimator()` Returns the `DirectionEstimator` object.
`java.lang.String` `getFormValue()` Returns the value property of the input element that backs this widget.
`java.lang.String` `getHTML()` Gets this object's contents as HTML.
`java.lang.String` `getName()` Gets the widget's name.
`int` `getTabIndex()` Gets the tab index.
`java.lang.String` `getText()` Gets this object's text.
`HasDirection.Direction` `getTextDirection()` Gets the direction of this object's text.
`java.lang.Boolean` `getValue()` Determines whether this check box is currently checked.
`boolean` `getWordWrap()` Gets whether word-wrapping is enabled.
`boolean` `isChecked()` Deprecated. Use `getValue()` instead
`boolean` `isEnabled()` Gets whether this widget is enabled.
`protected void` `onEnsureDebugId(java.lang.String baseID)` Affected Elements: -label = label next to checkbox.
`protected void` `onLoad()` This method is called when a widget is attached to the browser's document.
`protected void` `onUnload()` This method is called when a widget is detached from the browser's document.
`protected void` `replaceInputElement(Element elem)` Replace the current input element with a new one.
`protected void` `replaceInputElement(Element elem)` Deprecated. Call and use `replaceInputElement(Element)` instead.
`void` `setAccessKey(char key)` Sets the widget's 'access key'.
`void` `setChecked(boolean checked)` Deprecated. Use `setValue(Boolean)` instead
`void` `setDirectionEstimator(boolean enabled)` Toggles on / off direction estimation.
`void` `setDirectionEstimator(DirectionEstimator directionEstimator)` Sets the `DirectionEstimator` object.
`void` `setEnabled(boolean enabled)` Sets whether this widget is enabled.
`void` `setFocus(boolean focused)` Explicitly focus/unfocus this widget.
`void` `setFormValue(java.lang.String value)` Set the value property on the input element that backs this widget.
`void` `setHTML(SafeHtml html, HasDirection.Direction dir)` Sets this object's html, also declaring its direction.
`void` `setHTML(java.lang.String html)` Sets this object's contents via HTML.
`void` `setName(java.lang.String name)` Sets the widget's name.
`void` `setTabIndex(int index)` Sets the widget's position in the tab index.
`void` `setText(java.lang.String text)` Sets this object's text.
`void` `setText(java.lang.String text, HasDirection.Direction dir)` Sets this object's text, also declaring its direction.
`void` `setValue(java.lang.Boolean value)` Checks or unchecks the check box.
`void` `setValue(java.lang.Boolean value, boolean fireEvents)` Checks or unchecks the check box, firing `ValueChangeEvent` if appropriate.
`void` `setWordWrap(boolean wrap)` Sets whether word-wrapping is enabled.
`void` `sinkEvents(int eventBitsToAdd)` Overridden to defer the call to super.sinkEvents until the first time this widget is attached to the dom, as a performance enhancement.

### Methods inherited from class com.google.gwt.user.client.ui.ButtonBase

`setHTML`

### Methods inherited from class com.google.gwt.user.client.ui.FocusWidget

`addBlurHandler, addClickHandler, addClickListener, addDoubleClickHandler, addDragEndHandler, addDragEnterHandler, addDragHandler, addDragLeaveHandler, addDragOverHandler, addDragStartHandler, addDropHandler, addFocusHandler, addFocusListener, addGestureChangeHandler, addGestureEndHandler, addGestureStartHandler, addKeyboardListener, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addMouseDownHandler, addMouseListener, addMouseMoveHandler, addMouseOutHandler, addMouseOverHandler, addMouseUpHandler, addMouseWheelHandler, addMouseWheelListener, addTouchCancelHandler, addTouchEndHandler, addTouchMoveHandler, addTouchStartHandler, getFocusImpl, onAttach, removeClickListener, removeFocusListener, removeKeyboardListener, removeMouseListener, removeMouseWheelListener`

### Methods inherited from class com.google.gwt.user.client.ui.Widget

`addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, doAttachChildren, doDetachChildren, ensureHandlers, fireEvent, getHandlerCount, getHandlerManager, getLayoutData, getParent, isAttached, isOrWasAttached, onBrowserEvent, onDetach, removeFromParent, replaceElement, setLayoutData, setParent, unsinkEvents`

### Methods inherited from class com.google.gwt.user.client.ui.UIObject

`addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, removeStyleDependentName, removeStyleName, resolvePotentialElement, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, toString`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface com.google.gwt.event.shared.HasHandlers

`fireEvent`

### Methods inherited from interface com.google.gwt.safehtml.client.HasSafeHtml

`setHTML`

### Field Detail

#### DEFAULT_DIRECTION_ESTIMATOR

    public static final DirectionEstimator DEFAULT_DIRECTION_ESTIMATOR

#### directionalTextHelper

    final DirectionalTextHelper directionalTextHelper

#### inputElem

    InputElement inputElem

#### labelElem

    LabelElement labelElem

### Constructor Detail

#### CheckBox

    public CheckBox()

Creates a check box with no label.

#### CheckBox

    public CheckBox(SafeHtml label)

Creates a check box with the specified text label.

Parameters:
  `label` - the check box's label

#### CheckBox

    public CheckBox(SafeHtml label,
                    HasDirection.Direction dir)

Creates a check box with the specified text label.

Parameters:
  `label` - the check box's label
  `dir` - the text's direction. Note that `DEFAULT` means direction should be inherited from the widget's parent element.

#### CheckBox

    public CheckBox(SafeHtml label,
                    DirectionEstimator directionEstimator)

Creates a check box with the specified text label.

Parameters:
  `label` - the check box's label
  `directionEstimator` - A DirectionEstimator object used for automatic direction adjustment. For convenience, `DEFAULT_DIRECTION_ESTIMATOR` can be used.

#### CheckBox

    public CheckBox(java.lang.String label)

Creates a check box with the specified text label.

Parameters:
  `label` - the check box's label

#### CheckBox

    public CheckBox(java.lang.String label,
                    HasDirection.Direction dir)

Creates a check box with the specified text label.

Parameters:
  `label` - the check box's label
  `dir` - the text's direction. Note that `DEFAULT` means direction should be inherited from the widget's parent element.

#### CheckBox

    public CheckBox(java.lang.String label,
                    DirectionEstimator directionEstimator)

Creates a label with the specified text and a default direction estimator.

Parameters:
  `label` - the check box's label
  `directionEstimator` - A DirectionEstimator object used for automatic direction adjustment. For convenience, `DEFAULT_DIRECTION_ESTIMATOR` can be used.

#### CheckBox

    public CheckBox(java.lang.String label,
                    boolean asHTML)

Creates a check box with the specified text label.

Parameters:
  `label` - the check box's label
  `asHTML` - `true` to treat the specified label as html

#### CheckBox

    protected CheckBox(Element elem)

### Method Detail

#### addValueChangeHandler

    public HandlerRegistration addValueChangeHandler(ValueChangeHandler<java.lang.Boolean> handler)

Description copied from interface: `HasValueChangeHandlers`
Adds a `ValueChangeEvent` handler.

Specified by:
  `addValueChangeHandler` in interface `HasValueChangeHandlers<java.lang.Boolean>`
Parameters:
  `handler` - the handler
Returns:
  the registration for the event

#### asEditor

    public LeafValueEditor<java.lang.Boolean> asEditor()

Description copied from interface: `IsEditor`
Returns the Editor encapsulated by the view object.

Specified by:
  `asEditor` in interface `IsEditor<LeafValueEditor<java.lang.Boolean>>`
Returns:
  an `Editor` of type E

#### getDirectionEstimator

    public DirectionEstimator getDirectionEstimator()

Description copied from interface: `HasDirectionEstimator`
Returns the `DirectionEstimator` object.

Specified by:
  `getDirectionEstimator` in interface `HasDirectionEstimator`

#### getFormValue

    public java.lang.String getFormValue()

Returns the value property of the input element that backs this widget. This is the value that will be associated with the CheckBox name and submitted to the server if a `FormPanel` that holds it is submitted and the box is checked.

Don't confuse this with `getValue()`, which returns true or false if the widget is checked.

#### getHTML

    public java.lang.String getHTML()

Description copied from interface: `HasHTML`
Gets this object's contents as HTML.

Specified by:
  `getHTML` in interface `HasHTML`
Overrides:
  `getHTML` in class `ButtonBase`
Returns:
  the object's HTML

#### getName

    public java.lang.String getName()

Description copied from interface: `HasName`
Gets the widget's name.

Specified by:
  `getName` in interface `HasName`
Returns:
  the widget's name

#### getTabIndex

    public int getTabIndex()

Description copied from class: `FocusWidget`
Gets the tab index.

Specified by:
  `getTabIndex` in interface `Focusable`
Overrides:
  `getTabIndex` in class `FocusWidget`
Returns:
  the tab index

#### getText

    public java.lang.String getText()

Description copied from interface: `HasText`
Gets this object's text.

Specified by:
  `getText` in interface `HasText`
Overrides:
  `getText` in class `ButtonBase`
Returns:
  the object's text

#### getTextDirection

    public HasDirection.Direction getTextDirection()

Description copied from interface: `HasDirectionalText`
Gets the direction of this object's text.

Specified by:
  `getTextDirection` in interface `HasDirectionalText`
Returns:
  the direction of this object's text

#### getValue

    public java.lang.Boolean getValue()

Determines whether this check box is currently checked.

Note that this does not return the value property of the checkbox input element wrapped by this widget. For access to that property, see `getFormValue()`

Specified by:
  `getValue` in interface `TakesValue<java.lang.Boolean>`
Specified by:
  `getValue` in interface `HasValue<java.lang.Boolean>`
Returns:
  `true` if the check box is checked, false otherwise. Will not return null
See Also:
  `TakesValue.setValue(V)`

#### getWordWrap

    public boolean getWordWrap()

Description copied from interface: `HasWordWrap`
Gets whether word-wrapping is enabled.

Specified by:
  `getWordWrap` in interface `HasWordWrap`
Returns:
  `true` if word-wrapping is enabled.

#### isChecked

    @Deprecated
    public boolean isChecked()

Deprecated. Use `getValue()` instead
Determines whether this check box is currently checked.

Returns:
  `true` if the check box is checked

#### isEnabled

    public boolean isEnabled()

Description copied from class: `FocusWidget`
Gets whether this widget is enabled.

Specified by:
  `isEnabled` in interface `HasEnabled`
Overrides:
  `isEnabled` in class `FocusWidget`
Returns:
  `true` if the widget is enabled

#### setAccessKey

    public void setAccessKey(char key)

Description copied from interface: `Focusable`
Sets the widget's 'access key'. This key is used (in conjunction with a browser-specific modifier key) to automatically focus the widget.

Specified by:
  `setAccessKey` in interface `Focusable`
Overrides:
  `setAccessKey` in class `FocusWidget`
Parameters:
  `key` - the widget's access key

#### setChecked

    @Deprecated
    public void setChecked(boolean checked)

Deprecated. Use `setValue(Boolean)` instead
Checks or unchecks this check box. Does not fire `ValueChangeEvent`. (If you want the event to fire, use `setValue(Boolean, boolean)`)

Parameters:
  `checked` - `true` to check the check box.

#### setDirectionEstimator

    public void setDirectionEstimator(boolean enabled)

Toggles on / off direction estimation.

See note at `setDirectionEstimator(DirectionEstimator)`.

Specified by:
  `setDirectionEstimator` in interface `HasDirectionEstimator`
Parameters:
  `enabled` - Whether to enable direction estimation. If `true`, sets the `DirectionEstimator` object to a default `DirectionEstimator`.

#### setDirectionEstimator

    public void setDirectionEstimator(DirectionEstimator directionEstimator)

Sets the `DirectionEstimator` object.

Note: DirectionEstimator should be set before the label has any content; it's highly recommended to set it using a constructor. Reason: if the label already has non-empty content, this will update its direction according to the new estimator's result. This may cause flicker, and thus should be avoided.

Specified by:
  `setDirectionEstimator` in interface `HasDirectionEstimator`
Parameters:
  `directionEstimator` - The `DirectionEstimator` to be set. `null` means turning off direction estimation.

#### setEnabled

    public void setEnabled(boolean enabled)

Description copied from class: `FocusWidget`
Sets whether this widget is enabled.

Specified by:
  `setEnabled` in interface `HasEnabled`
Overrides:
  `setEnabled` in class `FocusWidget`
Parameters:
  `enabled` - `true` to enable the widget, `false` to disable it

#### setFocus

    public void setFocus(boolean focused)

Description copied from interface: `Focusable`
Explicitly focus/unfocus this widget. Only one widget can have focus at a time, and the widget that does will receive all keyboard events. NOTE: Most browsers fire FocusEvents asynchronously. Especially within GWT tests, you'll need to make your test asynchronous to properly do verifications. See `GWTTestCase#delayTestFinish` for more information on how to do this.

Specified by:
  `setFocus` in interface `Focusable`
Overrides:
  `setFocus` in class `FocusWidget`
Parameters:
  `focused` - whether this widget should take focus or release it

#### setFormValue

    public void setFormValue(java.lang.String value)

Set the value property on the input element that backs this widget. This is the value that will be associated with the CheckBox's name and submitted to the server if a `FormPanel` that holds it is submitted and the box is checked.

Don't confuse this with `setValue(java.lang.Boolean)`, which actually checks and unchecks the box.

Parameters:
  `value` -

#### setHTML

    public void setHTML(SafeHtml html,
                        HasDirection.Direction dir)

Description copied from interface: `HasDirectionalSafeHtml`
Sets this object's html, also declaring its direction.

Specified by:
  `setHTML` in interface `HasDirectionalSafeHtml`
Parameters:
  `html` - the object's new html
  `dir` - the html's direction

#### setHTML

    public void setHTML(java.lang.String html)

Description copied from interface: `HasHTML`
Sets this object's contents via HTML. Use care when setting an object's HTML; it is an easy way to expose script-based security problems. Consider using `HasText.setText(String)` whenever possible.

Specified by:
  `setHTML` in interface `HasHTML`
Overrides:
  `setHTML` in class `ButtonBase`
Parameters:
  `html` - the object's new HTML

#### setName

    public void setName(java.lang.String name)

Description copied from interface: `HasName`
Sets the widget's name.

Specified by:
  `setName` in interface `HasName`
Parameters:
  `name` - the widget's new name

#### setTabIndex

    public void setTabIndex(int index)

Description copied from interface: `Focusable`
Sets the widget's position in the tab index. If more than one widget has the same tab index, each such widget will receive focus in an arbitrary order. Setting the tab index to `-1` will cause this widget to be removed from the tab order.

Specified by:
  `setTabIndex` in interface `Focusable`
Overrides:
  `setTabIndex` in class `FocusWidget`
Parameters:
  `index` - the widget's tab index

#### setText

    public void setText(java.lang.String text)

Description copied from interface: `HasText`
Sets this object's text.

Specified by:
  `setText` in interface `HasText`
Overrides:
  `setText` in class `ButtonBase`
Parameters:
  `text` - the object's new text

#### setText

    public void setText(java.lang.String text,
                        HasDirection.Direction dir)

Description copied from interface: `HasDirectionalText`
Sets this object's text, also declaring its direction.

Specified by:
  `setText` in interface `HasDirectionalText`
Parameters:
  `text` - the object's new text
  `dir` - the text's direction

#### setValue

    public void setValue(java.lang.Boolean value)

Checks or unchecks the check box.

Note that this does not set the value property of the checkbox input element wrapped by this widget. For access to that property, see `setFormValue(String)`

Specified by:
  `setValue` in interface `TakesValue<java.lang.Boolean>`
Specified by:
  `setValue` in interface `HasValue<java.lang.Boolean>`
Parameters:
  `value` - true to check, false to uncheck; null value implies false
See Also:
  `TakesValue.getValue()`

#### setValue

    public void setValue(java.lang.Boolean value,
                         boolean fireEvents)

Checks or unchecks the check box, firing `ValueChangeEvent` if appropriate.

Note that this does not set the value property of the checkbox input element wrapped by this widget. For access to that property, see `setFormValue(String)`

Specified by:
  `setValue` in interface `HasValue<java.lang.Boolean>`
Parameters:
  `value` - true to check, false to uncheck; null value implies false
  `fireEvents` - If true, and value has changed, fire a `ValueChangeEvent`

#### setWordWrap

    public void setWordWrap(boolean wrap)

Description copied from interface: `HasWordWrap`
Sets whether word-wrapping is enabled.

Specified by:
  `setWordWrap` in interface `HasWordWrap`
Parameters:
  `wrap` - `true` to enable word-wrapping.

#### sinkEvents

    public void sinkEvents(int eventBitsToAdd)

Description copied from class: `Widget`
Overridden to defer the call to super.sinkEvents until the first time this widget is attached to the dom, as a performance enhancement. Subclasses wishing to customize sinkEvents can preserve this deferred sink behavior by putting their implementation behind a check of `isOrWasAttached()`:

      @Override
     public void sinkEvents(int eventBitsToAdd) {
       if (isOrWasAttached()) {
         / * customized sink code goes here  */
       } else {
         super.sinkEvents(eventBitsToAdd);
      }
    }

Overrides:
  `sinkEvents` in class `Widget`
Parameters:
  `eventBitsToAdd` - a bitfield representing the set of events to be added to this element's event set
See Also:
  `Event`

#### ensureDomEventHandlers

    protected void ensureDomEventHandlers()

#### onEnsureDebugId

    protected void onEnsureDebugId(java.lang.String baseID)

Affected Elements:

- -label = label next to checkbox.

Overrides:
  `onEnsureDebugId` in class `UIObject`
Parameters:
  `baseID` - the base ID used by the main element
See Also:
  `UIObject.onEnsureDebugId(String)`

#### onLoad

    protected void onLoad()

This method is called when a widget is attached to the browser's document. onAttach needs special handling for the CheckBox case. Must still call `Widget.onAttach()` to preserve the `onAttach` contract.

Overrides:
  `onLoad` in class `Widget`

#### onUnload

    protected void onUnload()

This method is called when a widget is detached from the browser's document. Overridden because of IE bug that throws away checked state and in order to clear the event listener off of the `inputElem`.

Overrides:
  `onUnload` in class `Widget`

#### replaceInputElement

    protected void replaceInputElement(Element elem)

Replace the current input element with a new one. Preserves all state except for the name property, for nasty reasons related to radio button grouping. (See implementation of `RadioButton.setName(java.lang.String)`.)

Parameters:
  `elem` - the new input element

#### replaceInputElement

    @Deprecated
    protected void replaceInputElement(Element elem)

Deprecated. Call and use `replaceInputElement(Element)` instead.