com.google.gwt.user.client.ui

## Class AbstractImagePrototype

- java.lang.Object
- - com.google.gwt.user.client.ui.AbstractImagePrototype

-     public abstract class AbstractImagePrototype
      extends java.lang.Object

  An opaque representation of a particular image such that the image can be accessed either as an HTML fragment or as an `Image` object. An image prototype can be thought of as an abstract image factory with additional capabilities.

  The `applyTo(Image)` method provides an efficient way to replace the contents of an existing `Image`. This is useful in cases where an image changes its appearance based on a user's action. Instead of creating two `Image` objects then alternately hiding/showing them, one can use the `applyTo(Image)` method of two `AbstractImagePrototype` objects to transform a single `Image` object between two (or more) visual representations. The use of `AbstractImagePrototypes` results in an cleaner and more efficient implementation.

  This class also provide methods for working with raw elements, using `createElement()` and `applyTo(ImagePrototypeElement)`.

  This class is also a useful way to encapsulate complex HTML that represents an image without actually instantiating `Image` objects. When constructing large HTML fragments, especially those that contain many images, `getHTML()` can be much more efficient.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `AbstractImagePrototype.ImagePrototypeElement` This corresponds to the top Element of the DOM structure created by `createElement()`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractImagePrototype()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `applyTo(AbstractImagePrototype.ImagePrototypeElement imageElement)` Transforms an existing `AbstractImagePrototype.ImagePrototypeElement` into the image represented by this prototype.
    `abstract void` | `applyTo(Image image)` Transforms an existing `Image` into the image represented by this prototype.
    `static AbstractImagePrototype` | `create(ImageResource resource)` Create an AbstractImagePrototype backed by a ClientBundle ImageResource.
    `AbstractImagePrototype.ImagePrototypeElement` | `createElement()` Creates a new `Element` based on the image represented by this prototype.
    `abstract Image` | `createImage()` Creates a new `Image` instance based on the image represented by this prototype.
    `java.lang.String` | `getHTML()` Gets an HTML fragment that displays the image represented by this prototype.
    `SafeHtml` | `getSafeHtml()` Gets an HTML fragment that displays the image represented by this prototype.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### AbstractImagePrototype

          public AbstractImagePrototype()

  - ### Method Detail

    - #### create

          public static AbstractImagePrototype create(ImageResource resource)

      Create an AbstractImagePrototype backed by a ClientBundle ImageResource. This method provides an API compatibility mapping for the new ImageResource API.
      Parameters:
        `resource` - an ImageResource produced by a ClientBundle
      Returns:
        an AbstractImagePrototype that displays the contents of the ImageResource

    - #### applyTo

          public abstract void applyTo(Image image)

      Transforms an existing `Image` into the image represented by this prototype.
      Parameters:
        `image` - the instance to be transformed to match this prototype

    - #### applyTo

          public void applyTo(AbstractImagePrototype.ImagePrototypeElement imageElement)

      Transforms an existing `AbstractImagePrototype.ImagePrototypeElement` into the image represented by this prototype.
      Parameters:
        `imageElement` - an `ImagePrototypeElement` created by `createElement()`

    - #### createElement

          public AbstractImagePrototype.ImagePrototypeElement createElement()

      Creates a new `Element` based on the image represented by this prototype. The DOM structure may not necessarily a simple `<img>` element. It may be a more complex structure that should be treated opaquely.
      Returns:
        the `ImagePrototypeElement` corresponding to the image represented by this prototype

    - #### createImage

          public abstract Image createImage()

      Creates a new `Image` instance based on the image represented by this prototype.
      Returns:
        a new `Image` based on this prototype

    - #### getHTML

          public java.lang.String getHTML()

      Gets an HTML fragment that displays the image represented by this prototype. The HTML returned is not necessarily a simple `<img>` element. It may be a more complex structure that should be treated opaquely.

      The default implementation calls `getSafeHtml()`.

      Returns:
        the HTML representation of this prototype

    - #### getSafeHtml

          public SafeHtml getSafeHtml()

      Gets an HTML fragment that displays the image represented by this prototype. The HTML returned is not necessarily a simple `<img>` element. It may be a more complex structure that should be treated opaquely.

      The default implementation throws an `UnsupportedOperationException`.

      Returns:
        the HTML representation of this prototype