java.lang.Object
   ↳ com.google.gwt.user.client.ui.UIObject
     ↳ com.google.gwt.user.client.ui.Widget
       ↳ com.google.gwt.user.client.ui.Image

Class Overview

A widget that displays the image at a given URL. The image can be in 'unclipped' mode (the default) or 'clipped' mode. In clipped mode, a viewport is overlaid on top of the image so that a subset of the image will be displayed. In unclipped mode, there is no viewport - the entire image will be visible. Whether an image is in clipped or unclipped mode depends on how the image is constructed, and how it is transformed after construction. Methods will operate differently depending on the mode that the image is in. These differences are detailed in the documentation for each method.

If an image transitions between clipped mode and unclipped mode, any Element-specific attributes added by the user (including style attributes, style names, and style modifiers), except for event listeners, will be lost.

CSS Style Rules

.gwt-Image
The outer element
Tranformations between clipped and unclipped state will result in a loss of any style names that were set/added; the only style names that are preserved are those that are mentioned in the static CSS style rules. Due to browser-specific HTML constructions needed to achieve the clipping effect, certain CSS attributes, such as padding and background, may not work as expected when an image is in clipped mode. These limitations can usually be easily worked around by encapsulating the image in a container widget that can itself be styled.

Example

{@example com.google.gwt.examples.ImageExample}

Summary

[Expand]
Inherited Constants
From class com.google.gwt.user.client.ui.UIObject
Public Constructors
Image()
Creates an empty image.
Image(ImageResource resource)
Creates an image whose size and content are defined by an ImageResource.
Image(String url)
Creates an image with a specified URL.
Image(String url, int left, int top, int width, int height)
Creates a clipped image with a specified URL and visibility rectangle.
Protected Constructors
Image(Element element)
This constructor may be used by subclasses to explicitly use an existing element.
Public Methods
HandlerRegistration addClickHandler(ClickHandler handler)
Adds a ClickEvent handler.
void addClickListener(ClickListener listener)
This method is deprecated. Use addClickHandler(ClickHandler) instead
HandlerRegistration addDoubleClickHandler(DoubleClickHandler handler)
Adds a DoubleClickEvent handler.
HandlerRegistration addErrorHandler(ErrorHandler handler)
Adds an ErrorEvent handler.
HandlerRegistration addGestureChangeHandler(GestureChangeHandler handler)
Adds a GestureChangeEvent handler.
HandlerRegistration addGestureEndHandler(GestureEndHandler handler)
Adds a GestureEndEvent handler.
HandlerRegistration addGestureStartHandler(GestureStartHandler handler)
Adds a GestureStartEvent handler.
HandlerRegistration addLoadHandler(LoadHandler handler)
Adds a LoadEvent handler.
void addLoadListener(LoadListener listener)
This method is deprecated. use LoadHandler and ErrorHandler instead
HandlerRegistration addMouseDownHandler(MouseDownHandler handler)
Adds a MouseDownEvent handler.
void addMouseListener(MouseListener listener)
HandlerRegistration addMouseMoveHandler(MouseMoveHandler handler)
Adds a MouseMoveEvent handler.
HandlerRegistration addMouseOutHandler(MouseOutHandler handler)
Adds a MouseOutEvent handler.
HandlerRegistration addMouseOverHandler(MouseOverHandler handler)
Adds a MouseOverEvent handler.
HandlerRegistration addMouseUpHandler(MouseUpHandler handler)
Adds a MouseUpEvent handler.
HandlerRegistration addMouseWheelHandler(MouseWheelHandler handler)
Adds a MouseWheelEvent handler.
void addMouseWheelListener(MouseWheelListener listener)
This method is deprecated. Use addMouseWheelHandler(MouseWheelHandler) instead
HandlerRegistration addTouchCancelHandler(TouchCancelHandler handler)
Adds a TouchCancelEvent handler.
HandlerRegistration addTouchEndHandler(TouchEndHandler handler)
Adds a TouchEndEvent handler.
HandlerRegistration addTouchMoveHandler(TouchMoveHandler handler)
Adds a TouchMoveEvent handler.
HandlerRegistration addTouchStartHandler(TouchStartHandler handler)
Adds a TouchStartEvent handler.
String getAltText()
Gets the alternate text for the image.
int getHeight()
Gets the height of the image.
int getOriginLeft()
Gets the horizontal co-ordinate of the upper-left vertex of the image's visibility rectangle.
int getOriginTop()
Gets the vertical co-ordinate of the upper-left vertex of the image's visibility rectangle.
String getUrl()
Gets the URL of the image.
int getWidth()
Gets the width of the image.
void onBrowserEvent(Event event)
Fired whenever a browser event is received.
static void prefetch(String url)
Causes the browser to pre-fetch the image at a given URL.
void removeClickListener(ClickListener listener)
This method is deprecated. Use the removeHandler() method on the object returned by addClickHandler(ClickHandler) instead
void removeLoadListener(LoadListener listener)
This method is deprecated. Use the removeHandler() method on the object returned by an add*Handler method instead
void removeMouseListener(MouseListener listener)
This method is deprecated. Use the removeHandler() method on the object returned by an add*Handler method instead
void removeMouseWheelListener(MouseWheelListener listener)
This method is deprecated. Use the removeHandler() method on the object returned by addMouseWheelHandler(MouseWheelHandler) instead
void setAltText(String altText)
Sets the alternate text of the image for user agents that can't render the image.
void setResource(ImageResource resource)
Sets the url and the visibility rectangle for the image at the same time, based on an ImageResource instance.
void setUrl(String url)
Sets the URL of the image to be displayed.
void setUrlAndVisibleRect(String url, int left, int top, int width, int height)
Sets the url and the visibility rectangle for the image at the same time.
void setVisibleRect(int left, int top, int width, int height)
Sets the visibility rectangle of an image.
static Image wrap(Element element)
Creates a Image widget that wraps an existing <img> element.
Protected Methods
void onLoad()
This method is called immediately after a widget becomes attached to the browser's document.
[Expand]
Inherited Methods
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.HasClickHandlers
From interface com.google.gwt.event.dom.client.HasDoubleClickHandlers
From interface com.google.gwt.event.dom.client.HasErrorHandlers
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.HasLoadHandlers
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.user.client.EventListener
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.SourcesLoadEvents
From interface com.google.gwt.user.client.ui.SourcesMouseEvents

Public Constructors

public Image ()

Creates an empty image.

public Image (ImageResource resource)

Creates an image whose size and content are defined by an ImageResource.

Parameters
resource the ImageResource to be displayed

public Image (String url)

Creates an image with a specified URL. The load event will be fired once the image at the given URL has been retrieved by the browser.

Parameters
url the URL of the image to be displayed

public Image (String url, int left, int top, int width, int height)

Creates a clipped image with a specified URL and visibility rectangle. The visibility rectangle is declared relative to the the rectangle which encompasses the entire image, which has an upper-left vertex of (0,0). The load event will be fired immediately after the object has been constructed (i.e. potentially before the image has been loaded in the browser). Since the width and height are specified explicitly by the user, this behavior will not cause problems with retrieving the width and height of a clipped image in a load event handler.

Parameters
url the URL of the image to be displayed
left the horizontal co-ordinate of the upper-left vertex of the visibility rectangle
top the vertical co-ordinate of the upper-left vertex of the visibility rectangle
width the width of the visibility rectangle
height the height of the visibility rectangle

Protected Constructors

protected Image (Element element)

This constructor may be used by subclasses to explicitly use an existing element. This element must be an <img> element.

Parameters
element the element to be used

Public Methods

public HandlerRegistration addClickHandler (ClickHandler handler)

Adds a ClickEvent handler.

Parameters
handler the click handler
Returns

public void addClickListener (ClickListener listener)

This method is deprecated.
Use addClickHandler(ClickHandler) instead

Adds a listener interface to receive click events.

Parameters
listener the listener interface to add

public HandlerRegistration addDoubleClickHandler (DoubleClickHandler handler)

Adds a DoubleClickEvent handler.

Parameters
handler the double click handler
Returns

public HandlerRegistration addErrorHandler (ErrorHandler handler)

Adds an ErrorEvent handler.

Parameters
handler the error handler
Returns

public HandlerRegistration addGestureChangeHandler (GestureChangeHandler handler)

Adds a GestureChangeEvent handler.

Parameters
handler the mouse down handler
Returns

public HandlerRegistration addGestureEndHandler (GestureEndHandler handler)

Adds a GestureEndEvent handler.

Parameters
handler the mouse down handler
Returns

public HandlerRegistration addGestureStartHandler (GestureStartHandler handler)

Adds a GestureStartEvent handler.

Parameters
handler the mouse down handler
Returns

public HandlerRegistration addLoadHandler (LoadHandler handler)

Adds a LoadEvent handler.

Parameters
handler the load handler
Returns

public void addLoadListener (LoadListener listener)

This method is deprecated.
use LoadHandler and ErrorHandler instead

Adds a listener interface to receive load events.

Parameters
listener the listener interface to add

public HandlerRegistration addMouseDownHandler (MouseDownHandler handler)

Adds a MouseDownEvent handler.

Parameters
handler the mouse down handler
Returns

public void addMouseListener (MouseListener listener)

This method is deprecated.
Use addMouseOverHandler(MouseOverHandler) addMouseMoveHandler(MouseMoveHandler), addMouseDownHandler(MouseDownHandler), addMouseUpHandler(MouseUpHandler) and addMouseOutHandler(MouseOutHandler) instead

Adds a listener interface to receive mouse events.

Parameters
listener the listener interface to add

public HandlerRegistration addMouseMoveHandler (MouseMoveHandler handler)

Adds a MouseMoveEvent handler.

Parameters
handler the mouse move handler
Returns

public HandlerRegistration addMouseOutHandler (MouseOutHandler handler)

Adds a MouseOutEvent handler.

Parameters
handler the mouse out handler
Returns

public HandlerRegistration addMouseOverHandler (MouseOverHandler handler)

Adds a MouseOverEvent handler.

Parameters
handler the mouse over handler
Returns

public HandlerRegistration addMouseUpHandler (MouseUpHandler handler)

Adds a MouseUpEvent handler.

Parameters
handler the mouse up handler
Returns

public HandlerRegistration addMouseWheelHandler (MouseWheelHandler handler)

Adds a MouseWheelEvent handler.

Parameters
handler the mouse wheel handler
Returns

public void addMouseWheelListener (MouseWheelListener listener)

This method is deprecated.
Use addMouseWheelHandler(MouseWheelHandler) instead

public HandlerRegistration addTouchCancelHandler (TouchCancelHandler handler)

Adds a TouchCancelEvent handler.

Parameters
handler the mouse down handler
Returns

public HandlerRegistration addTouchEndHandler (TouchEndHandler handler)

Adds a TouchEndEvent handler.

Parameters
handler the mouse down handler
Returns

public HandlerRegistration addTouchMoveHandler (TouchMoveHandler handler)

Adds a TouchMoveEvent handler.

Parameters
handler the mouse down handler
Returns

public HandlerRegistration addTouchStartHandler (TouchStartHandler handler)

Adds a TouchStartEvent handler.

Parameters
handler the mouse down handler
Returns

public String getAltText ()

Gets the alternate text for the image.

Returns
  • the alternate text for the image

public int getHeight ()

Gets the height of the image. When the image is in the unclipped state, the height of the image is not known until the image has been loaded (i.e. load event has been fired for the image).

Returns
  • the height of the image, or 0 if the height is unknown

public int getOriginLeft ()

Gets the horizontal co-ordinate of the upper-left vertex of the image's visibility rectangle. If the image is in the unclipped state, then the visibility rectangle is assumed to be the rectangle which encompasses the entire image, which has an upper-left vertex of (0,0).

Returns
  • the horizontal co-ordinate of the upper-left vertex of the image's visibility rectangle

public int getOriginTop ()

Gets the vertical co-ordinate of the upper-left vertex of the image's visibility rectangle. If the image is in the unclipped state, then the visibility rectangle is assumed to be the rectangle which encompasses the entire image, which has an upper-left vertex of (0,0).

Returns
  • the vertical co-ordinate of the upper-left vertex of the image's visibility rectangle

public String getUrl ()

Gets the URL of the image. The URL that is returned is not necessarily the URL that was passed in by the user. It may have been transformed to an absolute URL.

Returns
  • the image URL

public int getWidth ()

Gets the width of the image. When the image is in the unclipped state, the width of the image is not known until the image has been loaded (i.e. load event has been fired for the image).

Returns
  • the width of the image, or 0 if the width is unknown

public void onBrowserEvent (Event event)

Fired whenever a browser event is received.

Parameters
event the event received

public static void prefetch (String url)

Causes the browser to pre-fetch the image at a given URL.

Parameters
url the URL of the image to be prefetched

public void removeClickListener (ClickListener listener)

This method is deprecated.
Use the removeHandler() method on the object returned by addClickHandler(ClickHandler) instead

Removes a previously added listener interface.

Parameters
listener the listener interface to remove

public void removeLoadListener (LoadListener listener)

This method is deprecated.
Use the removeHandler() method on the object returned by an add*Handler method instead

Removes a previously added listener interface.

Parameters
listener the listener interface to remove

public void removeMouseListener (MouseListener listener)

This method is deprecated.
Use the removeHandler() method on the object returned by an add*Handler method instead

Removes a previously added listener interface.

Parameters
listener the listener interface to remove

public void removeMouseWheelListener (MouseWheelListener listener)

This method is deprecated.
Use the removeHandler() method on the object returned by addMouseWheelHandler(MouseWheelHandler) instead

public void setAltText (String altText)

Sets the alternate text of the image for user agents that can't render the image.

Parameters
altText the alternate text to set to

public void setResource (ImageResource resource)

Sets the url and the visibility rectangle for the image at the same time, based on an ImageResource instance. A single load event will be fired if either the incoming url or visiblity rectangle co-ordinates differ from the image's current url or current visibility rectangle co-ordinates. If the image is currently in the unclipped state, a call to this method will cause a transition to the clipped state.

Parameters
resource the ImageResource to display

public void setUrl (String url)

Sets the URL of the image to be displayed. If the image is in the clipped state, a call to this method will cause a transition of the image to the unclipped state. Regardless of whether or not the image is in the clipped or unclipped state, a load event will be fired.

Parameters
url the image URL

public void setUrlAndVisibleRect (String url, int left, int top, int width, int height)

Sets the url and the visibility rectangle for the image at the same time. A single load event will be fired if either the incoming url or visiblity rectangle co-ordinates differ from the image's current url or current visibility rectangle co-ordinates. If the image is currently in the unclipped state, a call to this method will cause a transition to the clipped state.

Parameters
url the image URL
left the horizontal coordinate of the upper-left vertex of the visibility rectangle
top the vertical coordinate of the upper-left vertex of the visibility rectangle
width the width of the visibility rectangle
height the height of the visibility rectangle

public void setVisibleRect (int left, int top, int width, int height)

Sets the visibility rectangle of an image. The visibility rectangle is declared relative to the the rectangle which encompasses the entire image, which has an upper-left vertex of (0,0). Provided that any of the left, top, width, and height parameters are different than the those values that are currently set for the image, a load event will be fired. If the image is in the unclipped state, a call to this method will cause a transition of the image to the clipped state. This transition will cause a load event to fire.

Parameters
left the horizontal coordinate of the upper-left vertex of the visibility rectangle
top the vertical coordinate of the upper-left vertex of the visibility rectangle
width the width of the visibility rectangle
height the height of the visibility rectangle

public static Image wrap (Element element)

Creates a Image widget that wraps an existing <img> element. This element must already be attached to the document. If the element is removed from the document, you must call detachNow(Widget).

Parameters
element the element to be wrapped

Protected Methods

protected void onLoad ()

This method is called immediately after a widget becomes attached to the browser's document.