public abstract class

CustomButton

extends ButtonBase
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
Known Direct Subclasses

Class Overview

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>
 

Summary

Nested Classes
class CustomButton.Face Represents a button's face. 
[Expand]
Inherited Constants
From class com.google.gwt.user.client.ui.UIObject
Public Constructors
CustomButton(Image upImage)
Constructor for CustomButton.
CustomButton(Image upImage, ClickHandler handler)
Constructor for CustomButton.
CustomButton(Image upImage, ClickListener listener)
This constructor is 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)
This constructor is deprecated. Use CustomButton(Image, Image, ClickHandler) instead
CustomButton(String upText)
Constructor for CustomButton.
CustomButton(String upText, ClickHandler handler)
Constructor for CustomButton.
CustomButton(String upText, ClickListener listener)
This constructor is deprecated. Use CustomButton(String, ClickListener) instead
CustomButton(String upText, String downText)
Constructor for CustomButton.
CustomButton(String upText, String downText, ClickHandler handler)
Constructor for CustomButton.
CustomButton(String upText, String downText, ClickListener listener)
This constructor is deprecated. Use CustomButton(String, String, ClickHandler) instead
Protected Constructors
CustomButton()
Constructor for CustomButton.
Public Methods
final CustomButton.Face getDownDisabledFace()
Gets the downDisabled face of the button.
final CustomButton.Face getDownFace()
Gets the down face of the button.
final CustomButton.Face getDownHoveringFace()
Gets the downHovering face of the button.
String getHTML()
Gets the current face's html.
int getTabIndex()
Gets the tab index.
String getText()
Gets the current face's text.
final CustomButton.Face getUpDisabledFace()
Gets the upDisabled face of the button.
final CustomButton.Face getUpFace()
Gets the up face of the button.
final CustomButton.Face getUpHoveringFace()
Gets the upHovering face of the button.
void onBrowserEvent(Event event)
Fired whenever a browser event is received.
void setAccessKey(char key)
Sets the widget's 'access key'.
final void setEnabled(boolean enabled)
Sets whether this button is enabled.
void setFocus(boolean focused)
Explicitly focus/unfocus this widget.
void setHTML(SafeHtml html)
Sets this object's contents via known-safe HTML.
void setHTML(String html)
Sets the current face's html.
void setTabIndex(int index)
Sets the widget's position in the tab index.
void setText(String text)
Sets the current face's text.
Protected Methods
boolean isDown()
Is this button down?
void onAttach()
Overridden on attach to ensure that a button face has been chosen before the button is displayed.
void onClick()
Called when the user finishes clicking on this button.
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.
void onClickStart()
Called when the user begins to click on this button.
void onDetach()

This method is called when a widget is detached from the browser's document.

void setDown(boolean down)
Sets whether this button is down.
[Expand]
Inherited Methods
From class com.google.gwt.user.client.ui.ButtonBase
From class com.google.gwt.user.client.ui.FocusWidget
From class com.google.gwt.user.client.ui.Widget
From class com.google.gwt.user.client.ui.UIObject
From class java.lang.Object
From interface com.google.gwt.event.dom.client.HasBlurHandlers
From interface com.google.gwt.event.dom.client.HasClickHandlers
From interface com.google.gwt.event.dom.client.HasDoubleClickHandlers
From interface com.google.gwt.event.dom.client.HasFocusHandlers
From interface com.google.gwt.event.dom.client.HasGestureChangeHandlers
From interface com.google.gwt.event.dom.client.HasGestureEndHandlers
From interface com.google.gwt.event.dom.client.HasGestureStartHandlers
From interface com.google.gwt.event.dom.client.HasKeyDownHandlers
From interface com.google.gwt.event.dom.client.HasKeyPressHandlers
From interface com.google.gwt.event.dom.client.HasKeyUpHandlers
From interface com.google.gwt.event.dom.client.HasMouseDownHandlers
From interface com.google.gwt.event.dom.client.HasMouseMoveHandlers
From interface com.google.gwt.event.dom.client.HasMouseOutHandlers
From interface com.google.gwt.event.dom.client.HasMouseOverHandlers
From interface com.google.gwt.event.dom.client.HasMouseUpHandlers
From interface com.google.gwt.event.dom.client.HasMouseWheelHandlers
From interface com.google.gwt.event.dom.client.HasTouchCancelHandlers
From interface com.google.gwt.event.dom.client.HasTouchEndHandlers
From interface com.google.gwt.event.dom.client.HasTouchMoveHandlers
From interface com.google.gwt.event.dom.client.HasTouchStartHandlers
From interface com.google.gwt.event.logical.shared.HasAttachHandlers
From interface com.google.gwt.event.shared.HasHandlers
From interface com.google.gwt.safehtml.client.HasSafeHtml
From interface com.google.gwt.user.client.EventListener
From interface com.google.gwt.user.client.ui.Focusable
From interface com.google.gwt.user.client.ui.HasEnabled
From interface com.google.gwt.user.client.ui.HasHTML
From interface com.google.gwt.user.client.ui.HasText
From interface com.google.gwt.user.client.ui.IsWidget
From interface com.google.gwt.user.client.ui.SourcesClickEvents
From interface com.google.gwt.user.client.ui.SourcesFocusEvents
From interface com.google.gwt.user.client.ui.SourcesKeyboardEvents
From interface com.google.gwt.user.client.ui.SourcesMouseEvents

Public Constructors

public CustomButton (Image upImage)

Constructor for CustomButton.

Parameters
upImage image for the default (up) face of the button

public CustomButton (Image upImage, ClickHandler handler)

Constructor for CustomButton.

Parameters
upImage image for the default (up) face of the button
handler the click handler

public CustomButton (Image upImage, ClickListener listener)

This constructor is deprecated.
Use CustomButton(Image, ClickHandler) instead

Constructor for CustomButton.

Parameters
upImage image for the default (up) face of the button
listener the click listener

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

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

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

This constructor is 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

public CustomButton (String upText)

Constructor for CustomButton.

Parameters
upText the text for the default (up) face of the button

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

public CustomButton (String upText, ClickListener listener)

This constructor is 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

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

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

public CustomButton (String upText, String downText, ClickListener listener)

This constructor is 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

Protected Constructors

protected CustomButton ()

Constructor for CustomButton.

Public Methods

public final CustomButton.Face getDownDisabledFace ()

Gets the downDisabled face of the button.

Returns
  • the downDisabled face

public final CustomButton.Face getDownFace ()

Gets the down face of the button.

Returns
  • the down face

public final CustomButton.Face getDownHoveringFace ()

Gets the downHovering face of the button.

Returns
  • the downHovering face

public String getHTML ()

Gets the current face's html.

Returns
  • current face's html

public int getTabIndex ()

Gets the tab index.

Returns
  • the tab index

public String getText ()

Gets the current face's text.

Returns
  • current face's text

public final CustomButton.Face getUpDisabledFace ()

Gets the upDisabled face of the button.

Returns
  • the upDisabled face

public final CustomButton.Face getUpFace ()

Gets the up face of the button.

Returns
  • the up face

public final CustomButton.Face getUpHoveringFace ()

Gets the upHovering face of the button.

Returns
  • the upHovering face

public void onBrowserEvent (Event event)

Fired whenever a browser event is received.

Parameters
event the event received

public void setAccessKey (char key)

Sets the widget's 'access key'. This key is used (in conjunction with a browser-specific modifier key) to automatically focus the widget.

Parameters
key the widget's access key

public final void setEnabled (boolean enabled)

Sets whether this button is enabled.

Parameters
enabled true to enable the button, false to disable it

public void setFocus (boolean focused)

Explicitly focus/unfocus this widget. Only one widget can have focus at a time, and the widget that does will receive all keyboard events.

Parameters
focused whether this widget should take focus or release it

public void setHTML (SafeHtml html)

Sets this object's contents via known-safe HTML.

The object will behave exactly the same as when a widget's 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 setHTML(String), using this method cannot result in Cross-Site Scripting security vulnerabilities.

Parameters
html the object's new HTML, represented as a SafeHtml object

public void setHTML (String html)

Sets the current face's html.

Parameters
html html to set

public void setTabIndex (int index)

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.

Parameters
index the widget's tab index

public void setText (String text)

Sets the current face's text.

Parameters
text text to set

Protected Methods

protected boolean isDown ()

Is this button down?

Returns
  • true if the button is down

protected void onAttach ()

Overridden on attach to ensure that a button face has been chosen before the button is displayed.

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.

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.

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.

protected void onDetach ()

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 onUnload() method or use addAttachHandler(AttachEvent.Handler).

It is strongly recommended that you override onUnload() or 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.

protected void setDown (boolean down)

Sets whether this button is down.

Parameters
down true to press the button, false otherwise