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

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.