com.google.gwt.user.client.ui
Class Image

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

All Implemented Interfaces:

EventListener, SourcesClickEvents, SourcesLoadEvents, SourcesMouseEvents, SourcesMouseWheelEvents

public class Image
extends Widget
implements SourcesClickEvents, SourcesLoadEvents, SourcesMouseEvents, SourcesMouseWheelEvents

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 { }

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

public class ImageExample implements EntryPoint {

  private Label lbl = new Label();
  private Button btn = new Button("Clip this image");
  private Button btn2 = new Button("Restore image");

  public void onModuleLoad() {
    // Create an image, not yet referencing a URL. We make it final so that we
    // can manipulate the image object within the ClickHandlers for the buttons.
    final Image image = new Image();

    // Hook up a load listener, so that we can be informed if the image fails
    // to load.
    image.addLoadListener(new LoadListener() {
      public void onError(Widget sender) {
        lbl.setText("An error occurred while loading.");
      }

      public void onLoad(Widget sender) {
      }
    });

    // Point the image at a real URL.
    image.setUrl("http://www.google.com/images/logo.gif");

    // When the user clicks this button, we want to clip the image.
    btn.addClickListener(new ClickListener() {
      public void onClick(Widget sender) {
        image.setVisibleRect(70, 0, 47, 110);
      }
    });
    btn.setWidth("120px");

    // When the user clicks this button, we want to restore the image to its
    // unclipped state.
    btn2.addClickListener(new ClickListener() {
      public void onClick(Widget sender) {
        image.setUrl("http://www.google.com/images/logo.gif");
      }
    });
    btn2.setWidth("120px");

    // Add the image, label, and clip/restore buttons to the root panel.
    VerticalPanel panel = new VerticalPanel();
    panel.add(lbl);
    panel.add(image);

    HorizontalPanel buttonPanel = new HorizontalPanel();
    buttonPanel.add(btn);
    buttonPanel.add(btn2);

    panel.add(buttonPanel);

    RootPanel.get().add(panel);
  }
}

Constructor Summary

Image()
Creates an empty image.

Image(java.lang.String url)
Creates an image with a specified URL.

Image(java.lang.String url, int left, int top, int width, int height)
Creates a clipped image with a specified URL and visibility rectangle.

Method Summary

void	addClickListener(ClickListener listener) Adds a listener interface to receive click events.
void	addLoadListener(LoadListener listener) Adds a listener interface to receive load events.
void	addMouseListener(MouseListener listener) Adds a listener interface to receive mouse events.
void	addMouseWheelListener(MouseWheelListener listener) Adds a listener interface to receive mouse events.
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.
java.lang.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(java.lang.String url) Causes the browser to pre-fetch the image at a given URL.
void	removeClickListener(ClickListener listener) Removes a previously added listener interface.
void	removeLoadListener(LoadListener listener) Removes a previously added listener interface.
void	removeMouseListener(MouseListener listener) Removes a previously added listener interface.
void	removeMouseWheelListener(MouseWheelListener listener) Removes a previously added listener interface.
void	setUrl(java.lang.String url) Sets the URL of the image to be displayed.
void	setUrlAndVisibleRect(java.lang.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.

Methods inherited from class com.google.gwt.user.client.ui.Widget

doAttachChildren, doDetachChildren, getParent, isAttached, onAttach, onDetach, onLoad, onUnload, removeFromParent, setElement

Methods inherited from class com.google.gwt.user.client.ui.UIObject

addStyleDependentName, addStyleName, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, removeStyleDependentName, removeStyleName, setHeight, setPixelSize, setSize, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkEvents, toString, unsinkEvents

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Image

public Image()

Creates an empty image.

Image

public Image(java.lang.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

Image

public Image(java.lang.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

Method Detail

prefetch

public static void prefetch(java.lang.String url)

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

Parameters:

url - the URL of the image to be prefetched

addClickListener

public void addClickListener(ClickListener listener)

Description copied from interface: SourcesClickEvents

Adds a listener interface to receive click events.

Specified by:

addClickListener in interface SourcesClickEvents

Parameters:

listener - the listener interface to add

addLoadListener

public void addLoadListener(LoadListener listener)

Description copied from interface: SourcesLoadEvents

Adds a listener interface to receive load events.

Specified by:

addLoadListener in interface SourcesLoadEvents

Parameters:

listener - the listener interface to add

addMouseListener

public void addMouseListener(MouseListener listener)

Description copied from interface: SourcesMouseEvents

Adds a listener interface to receive mouse events.

Specified by:

addMouseListener in interface SourcesMouseEvents

Parameters:

listener - the listener interface to add

addMouseWheelListener

public void addMouseWheelListener(MouseWheelListener listener)

Description copied from interface: SourcesMouseWheelEvents

Adds a listener interface to receive mouse events.

Specified by:

addMouseWheelListener in interface SourcesMouseWheelEvents

Parameters:

listener - the listener interface to add

getHeight

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

getOriginLeft

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

getOriginTop

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

getUrl

public java.lang.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

getWidth

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

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

removeClickListener

public void removeClickListener(ClickListener listener)

Description copied from interface: SourcesClickEvents

Removes a previously added listener interface.

Specified by:

removeClickListener in interface SourcesClickEvents

Parameters:

listener - the listener interface to remove

removeLoadListener

public void removeLoadListener(LoadListener listener)

Description copied from interface: SourcesLoadEvents

Removes a previously added listener interface.

Specified by:

removeLoadListener in interface SourcesLoadEvents

Parameters:

listener - the listener interface to remove

removeMouseListener

public void removeMouseListener(MouseListener listener)

Description copied from interface: SourcesMouseEvents

Removes a previously added listener interface.

Specified by:

removeMouseListener in interface SourcesMouseEvents

Parameters:

listener - the listener interface to remove

removeMouseWheelListener

public void removeMouseWheelListener(MouseWheelListener listener)

Description copied from interface: SourcesMouseWheelEvents

Removes a previously added listener interface.

Specified by:

removeMouseWheelListener in interface SourcesMouseWheelEvents

Parameters:

listener - the listener interface to remove

setUrl

public void setUrl(java.lang.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

setUrlAndVisibleRect

public void setUrlAndVisibleRect(java.lang.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

setVisibleRect

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