com.google.gwt.user.client.ui

## Class CustomButton

- 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.CustomButton

- All Implemented Interfaces:
    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, HasHandlers, HasSafeHtml, EventListener, Focusable, HasEnabled, HasFocus, HasHTML, HasText, HasVisibility, IsWidget, SourcesClickEvents, SourcesFocusEvents, SourcesKeyboardEvents, SourcesMouseEvents
  Direct Known Subclasses:
    PushButton, ToggleButton

      public abstract class CustomButton
      extends ButtonBase

  CustomButton is a base button class with built in support for a set number of button faces. Each face has its own style modifier. For example, the state for down and hovering is assigned the CSS modifier down-hovering. So, if the button's overall style name is gwt-PushButton then when showing the `down-hovering` face, the button's style is gwt-PushButton-down-hovering. The overall style name can be used to change the style of the button irrespective of the current face.

  Each button face can be assigned is own image, text, or html contents. If no content is defined for a face, then the face will use the contents of another face. For example, if `down-hovering` does not have defined contents, it will use the contents defined by the `down` face.

  The supported faces are defined below:

  CSS style name | Getter method | description of face | defaults to contents of face
  up | `getUpFace()` | face shown when button is up | none
  down | `getDownFace()` | face shown when button is down | up
  up-hovering | `getUpHoveringFace()` | face shown when button is up and hovering | up
  up-disabled | `getUpDisabledFace()` | face shown when button is up and disabled | up
  down-hovering | `getDownHoveringFace()` | face shown when button is down and hovering | down
  down-disabled | `getDownDisabledFace()` | face shown when button is down and disabled | down

  ### Use in UiBinder Templates

  When working with CustomButton subclasses in `UiBinder` templates, you can set text and assign ImageResources for their various faces via child elements:

  <g:upFace>
  <g:downFace>
  <g:upHoveringFace>
  <g:downHoveringFace>
  <g:upDisabledFace>
  <g:downDisabledFace>
  Each face element can take an optional `image` attribute and an html body. For example:

       <ui:image field='downButton'/> <!-- define an ImageResource -->

       <g:PushButton ui:field='pushButton' enabled='true'>
         <g:upFace>
           <b>click me</b>
         </gwt:upFace>
         <g:upHoveringFace>
           <b>Click ME!</b>
         </gwt:upHoveringFace>

         <g:downFace image='{downButton}'/>
         <g:downHoveringFace image='{downButton}'/>
       </g:PushButton>

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `CustomButton.Face` Represents a button's face.

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

      `UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

  - ### Field Summary

    - ### 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
    Modifier | Constructor and Description
    --- | ---
    `protected` | `CustomButton()` Constructor for `CustomButton`.
    `` | `CustomButton(Image upImage)` Constructor for `CustomButton`.
    `` | `CustomButton(Image upImage, ClickHandler handler)` Constructor for `CustomButton`.
    `` | `CustomButton(Image upImage, ClickListener listener)` Deprecated. Use `CustomButton(Image, ClickHandler)` instead
    `` | `CustomButton(Image upImage, Image downImage)` Constructor for `CustomButton`.
    `` | `CustomButton(Image upImage, Image downImage, ClickHandler handler)` Constructor for `CustomButton`.
    `` | `CustomButton(Image upImage, Image downImage, ClickListener listener)` Deprecated. Use `CustomButton(Image, Image, ClickHandler)` instead
    `` | `CustomButton(java.lang.String upText)` Constructor for `CustomButton`.
    `` | `CustomButton(java.lang.String upText, ClickHandler handler)` Constructor for `CustomButton`.
    `` | `CustomButton(java.lang.String upText, ClickListener listener)` Deprecated. Use `CustomButton(String, ClickListener)` instead
    `` | `CustomButton(java.lang.String upText, java.lang.String downText)` Constructor for `CustomButton`.
    `` | `CustomButton(java.lang.String upText, java.lang.String downText, ClickHandler handler)` Constructor for `CustomButton`.
    `` | `CustomButton(java.lang.String upText, java.lang.String downText, ClickListener listener)` Deprecated. Use `CustomButton(String, String, ClickHandler)` instead

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) void` | `finishSetup()` Common setup between constructors.
    `(package private) void` | `fireClickListeners(Event nativeEvent)`
    `(package private) CustomButton.Face` | `getCurrentFace()` Gets the current face of the button.
    `CustomButton.Face` | `getDownDisabledFace()` Gets the downDisabled face of the button.
    `CustomButton.Face` | `getDownFace()` Gets the down face of the button.
    `CustomButton.Face` | `getDownHoveringFace()` Gets the downHovering face of the button.
    `java.lang.String` | `getHTML()` Gets the current face's html.
    `int` | `getTabIndex()` Gets the tab index.
    `java.lang.String` | `getText()` Gets the current face's text.
    `CustomButton.Face` | `getUpDisabledFace()` Gets the upDisabled face of the button.
    `CustomButton.Face` | `getUpFace()` Gets the up face of the button.
    `CustomButton.Face` | `getUpHoveringFace()` Gets the upHovering face of the button.
    `protected boolean` | `isDown()` Is this button down?
    `(package private) boolean` | `isHovering()` Is the mouse hovering over this button?
    `protected void` | `onAttach()` Overridden on attach to ensure that a button face has been chosen before the button is displayed.
    `void` | `onBrowserEvent(Event event)` Fired whenever a browser event is received.
    `protected void` | `onClick()` Called when the user finishes clicking on this button.
    `protected void` | `onClickCancel()` Called when the user aborts a click in progress; for example, by dragging the mouse outside of the button before releasing the mouse button.
    `protected void` | `onClickStart()` Called when the user begins to click on this button.
    `protected void` | `onDetach()` This method is called when a widget is detached from the browser's document.
    `void` | `setAccessKey(char key)` Sets the widget's 'access key'.
    `(package private) void` | `setCurrentFace(CustomButton.Face newFace)`
    `protected void` | `setDown(boolean down)` Sets whether this button is down.
    `void` | `setEnabled(boolean enabled)` Sets whether this button is enabled.
    `void` | `setFocus(boolean focused)` Explicitly focus/unfocus this widget.
    `(package private) void` | `setHovering(boolean hovering)` Sets whether this button is hovering.
    `void` | `setHTML(SafeHtml html)` Sets this object's contents via known-safe HTML.
    `void` | `setHTML(java.lang.String html)` Sets the current face's html.
    `void` | `setTabIndex(int index)` Sets the widget's position in the tab index.
    `void` | `setText(java.lang.String text)` Sets the current face's text.
    `(package private) void` | `toggleDown()` Toggle the up/down attribute.

    - ### 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, isEnabled, 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, onLoad, onUnload, removeFromParent, replaceElement, setLayoutData, setParent, sinkEvents, 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, onEnsureDebugId, 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`

- - ### Constructor Detail

    - #### CustomButton

          public CustomButton(Image upImage)

      Constructor for `CustomButton`.
      Parameters:
        `upImage` - image for the default (up) face of the button

    - #### CustomButton

          public CustomButton(Image upImage,
                              ClickHandler handler)

      Constructor for `CustomButton`.
      Parameters:
        `upImage` - image for the default (up) face of the button
        `handler` - the click handler

    - #### CustomButton

          @Deprecated
          public CustomButton(Image upImage,
                                          ClickListener listener)

      Deprecated. Use `CustomButton(Image, ClickHandler)` instead
      Constructor for `CustomButton`.
      Parameters:
        `upImage` - image for the default (up) face of the button
        `listener` - the click listener

    - #### CustomButton

          public CustomButton(Image upImage,
                              Image downImage)

      Constructor for `CustomButton`.
      Parameters:
        `upImage` - image for the default (up) face of the button
        `downImage` - image for the down face of the button

    - #### CustomButton

          public CustomButton(Image upImage,
                              Image downImage,
                              ClickHandler handler)

      Constructor for `CustomButton`.
      Parameters:
        `upImage` - image for the default (up) face of the button
        `downImage` - image for the down face of the button
        `handler` - clickListener

    - #### CustomButton

          @Deprecated
          public CustomButton(Image upImage,
                                          Image downImage,
                                          ClickListener listener)

      Deprecated. Use `CustomButton(Image, Image, ClickHandler)` instead
      Constructor for `CustomButton`.
      Parameters:
        `upImage` - image for the default (up) face of the button
        `downImage` - image for the down face of the button
        `listener` - clickListener

    - #### CustomButton

          public CustomButton(java.lang.String upText)

      Constructor for `CustomButton`.
      Parameters:
        `upText` - the text for the default (up) face of the button

    - #### CustomButton

          public CustomButton(java.lang.String upText,
                              ClickHandler handler)

      Constructor for `CustomButton`.
      Parameters:
        `upText` - the text for the default (up) face of the button
        `handler` - the click handler

    - #### CustomButton

          @Deprecated
          public CustomButton(java.lang.String upText,
                                          ClickListener listener)

      Deprecated. Use `CustomButton(String, ClickListener)` instead
      Constructor for `CustomButton`.
      Parameters:
        `upText` - the text for the default (up) face of the button
        `listener` - the click listener

    - #### CustomButton

          public CustomButton(java.lang.String upText,
                              java.lang.String downText)

      Constructor for `CustomButton`.
      Parameters:
        `upText` - the text for the default (up) face of the button
        `downText` - the text for the down face of the button

    - #### CustomButton

          public CustomButton(java.lang.String upText,
                              java.lang.String downText,
                              ClickHandler handler)

      Constructor for `CustomButton`.
      Parameters:
        `upText` - the text for the default (up) face of the button
        `downText` - the text for the down face of the button
        `handler` - the click handler

    - #### CustomButton

          @Deprecated
          public CustomButton(java.lang.String upText,
                                          java.lang.String downText,
                                          ClickListener listener)

      Deprecated. Use `CustomButton(String, String, ClickHandler)` instead
      Constructor for `CustomButton`.
      Parameters:
        `upText` - the text for the default (up) face of the button
        `downText` - the text for the down face of the button
        `listener` - the click listener

    - #### CustomButton

          protected CustomButton()

      Constructor for `CustomButton`.

  - ### Method Detail

    - #### getDownDisabledFace

          public final CustomButton.Face getDownDisabledFace()

      Gets the downDisabled face of the button.
      Returns:
        the downDisabled face

    - #### getDownFace

          public final CustomButton.Face getDownFace()

      Gets the down face of the button.
      Returns:
        the down face

    - #### getDownHoveringFace

          public final CustomButton.Face getDownHoveringFace()

      Gets the downHovering face of the button.
      Returns:
        the downHovering face

    - #### getHTML

          public java.lang.String getHTML()

      Gets the current face's html.
      Specified by:
        `getHTML` in interface `HasHTML`
      Overrides:
        `getHTML` in class `ButtonBase`
      Returns:
        current face's html

    - #### 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()

      Gets the current face's text.
      Specified by:
        `getText` in interface `HasText`
      Overrides:
        `getText` in class `ButtonBase`
      Returns:
        current face's text

    - #### getUpDisabledFace

          public final CustomButton.Face getUpDisabledFace()

      Gets the upDisabled face of the button.
      Returns:
        the upDisabled face

    - #### getUpFace

          public final CustomButton.Face getUpFace()

      Gets the up face of the button.
      Returns:
        the up face

    - #### getUpHoveringFace

          public final CustomButton.Face getUpHoveringFace()

      Gets the upHovering face of the button.
      Returns:
        the upHovering face

    - #### onBrowserEvent

          public void onBrowserEvent(Event event)

      Description copied from interface: `EventListener`
      Fired whenever a browser event is received.
      Specified by:
        `onBrowserEvent` in interface `EventListener`
      Overrides:
        `onBrowserEvent` in class `Widget`
      Parameters:
        `event` - the event received

    - #### 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

    - #### setEnabled

          public final void setEnabled(boolean enabled)

      Sets whether this button is enabled.
      Specified by:
        `setEnabled` in interface `HasEnabled`
      Overrides:
        `setEnabled` in class `FocusWidget`
      Parameters:
        `enabled` - `true` to enable the button, `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

    - #### setHTML

          public void setHTML(SafeHtml html)

      Description copied from interface: `HasSafeHtml`
      Sets this object's contents via known-safe HTML.

      The object will behave exactly the same as when a widget's `HasHTML.setHTML(String)` method is invoked; however the `SafeHtml` passed to this method observes the contract that it can be used in an HTML context without causing unsafe script execution. Thus, unlike `HasHTML.setHTML(String)`, using this method cannot result in Cross-Site Scripting security vulnerabilities.

      Specified by:
        `setHTML` in interface `HasSafeHtml`
      Overrides:
        `setHTML` in class `ButtonBase`
      Parameters:
        `html` - the object's new HTML, represented as a `SafeHtml` object

    - #### setHTML

          public void setHTML(java.lang.String html)

      Sets the current face's html.
      Specified by:
        `setHTML` in interface `HasHTML`
      Overrides:
        `setHTML` in class `ButtonBase`
      Parameters:
        `html` - html to set

    - #### 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)

      Sets the current face's text.
      Specified by:
        `setText` in interface `HasText`
      Overrides:
        `setText` in class `ButtonBase`
      Parameters:
        `text` - text to set

    - #### isDown

          protected boolean isDown()

      Is this button down?
      Returns:
        `true` if the button is down

    - #### onAttach

          protected void onAttach()

      Overridden on attach to ensure that a button face has been chosen before the button is displayed.
      Overrides:
        `onAttach` in class `FocusWidget`
      See Also:
        `Widget.onLoad()`, `Widget.doAttachChildren()`

    - #### onClick

          protected void onClick()

      Called when the user finishes clicking on this button. The default behavior is to fire the click event to listeners. Subclasses that override `onClickStart()` should override this method to restore the normal widget display.

    - #### onClickCancel

          protected void onClickCancel()

      Called when the user aborts a click in progress; for example, by dragging the mouse outside of the button before releasing the mouse button. Subclasses that override `onClickStart()` should override this method to restore the normal widget display.

    - #### onClickStart

          protected void onClickStart()

      Called when the user begins to click on this button. Subclasses may override this method to display the start of the click visually; such subclasses should also override `onClick()` and `onClickCancel()` to restore normal visual state. Each `onClickStart` will eventually be followed by either `onClick` or `onClickCancel`, depending on whether the click is completed.

    - #### onDetach

          protected void onDetach()

      Description copied from class: `Widget`

      This method is called when a widget is detached from the browser's document. To receive notification before a Widget is removed from the document, override the `Widget.onUnload()` method or use `Widget.addAttachHandler(com.google.gwt.event.logical.shared.AttachEvent.Handler)`.

      It is strongly recommended that you override `Widget.onUnload()` or `Widget.doDetachChildren()` instead of this method to avoid inconsistencies between logical and physical attachment states.

      Subclasses that override this method must call `super.onDetach()` to ensure that the Widget has been detached from the underlying Element. Failure to do so will result in application memory leaks due to circular references between DOM Elements and JavaScript objects.

      Overrides:
        `onDetach` in class `Widget`
      See Also:
        `Widget.onUnload()`, `Widget.doDetachChildren()`

    - #### setDown

          protected void setDown(boolean down)

      Sets whether this button is down.
      Parameters:
        `down` - `true` to press the button, `false` otherwise

    - #### finishSetup

          void finishSetup()

      Common setup between constructors.

    - #### fireClickListeners

          void fireClickListeners(Event nativeEvent)

    - #### getCurrentFace

          CustomButton.Face getCurrentFace()

      Gets the current face of the button.
      Returns:
        the current face

    - #### isHovering

          final boolean isHovering()

      Is the mouse hovering over this button?
      Returns:
        `true` if the mouse is hovering

    - #### setCurrentFace

          void setCurrentFace(CustomButton.Face newFace)

    - #### setHovering

          final void setHovering(boolean hovering)

      Sets whether this button is hovering.
      Parameters:
        `hovering` - is this button hovering?

    - #### toggleDown

          void toggleDown()

      Toggle the up/down attribute.