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

  • Constructor Details

    • 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(String upText)
      Constructor for CustomButton.
      Parameters:
      upText - the text for the default (up) face of the button

    • CustomButton

      public CustomButton(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(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(String upText, 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(String upText, 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(String upText, 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 Details

    • 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 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 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(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(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:

    • 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:

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