| /* |
| * Copyright 2008 Google Inc. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| * use this file except in compliance with the License. You may obtain a copy of |
| * the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| * License for the specific language governing permissions and limitations under |
| * the License. |
| */ |
| package com.google.gwt.user.client.ui; |
| |
| import com.google.gwt.dom.client.Element; |
| import com.google.gwt.resources.client.ImageResource; |
| import com.google.gwt.user.client.ui.impl.ClippedImagePrototype; |
| |
| /** |
| * An opaque representation of a particular image such that the image can be |
| * accessed either as an HTML fragment or as an {@link Image} object. An image |
| * prototype can be thought of as an abstract image factory with additional |
| * capabilities. |
| * |
| * <p> |
| * The {@link #applyTo(Image)} method provides an efficient way to replace the |
| * contents of an existing <code>Image</code>. This is useful in cases where an |
| * image changes its appearance based on a user's action. Instead of creating |
| * two <code>Image</code> objects then alternately hiding/showing them, one can |
| * use the {@link #applyTo(Image)} method of two |
| * <code>AbstractImagePrototype</code> objects to transform a single |
| * <code>Image</code> object between two (or more) visual representations. The |
| * use of <code>AbstractImagePrototypes</code> results in an cleaner and more |
| * efficient implementation. |
| * </p> |
| * |
| * <p> |
| * This class also provide methods for working with raw elements, using |
| * {@link #createElement()} and {@link #applyTo(ImagePrototypeElement)}. |
| * </p> |
| * |
| * <p> |
| * This class is also a useful way to encapsulate complex HTML that represents |
| * an image without actually instantiating <code>Image</code> objects. When |
| * constructing large HTML fragments, especially those that contain many images, |
| * {@link #getHTML()} can be much more efficient. |
| * </p> |
| */ |
| public abstract class AbstractImagePrototype { |
| |
| /** |
| * This corresponds to the top Element of the DOM structure created by |
| * {@link #createElement()}. |
| */ |
| public static class ImagePrototypeElement extends Element { |
| protected ImagePrototypeElement() { |
| } |
| } |
| |
| /** |
| * Create an AbstractImagePrototype backed by a ClientBundle ImageResource. |
| * This method provides an API compatibility mapping for the new ImageResource |
| * API. |
| * |
| * @param resource an ImageResource produced by a ClientBundle |
| * @return an AbstractImagePrototype that displays the contents of the |
| * ImageResource |
| */ |
| public static AbstractImagePrototype create(ImageResource resource) { |
| return new ClippedImagePrototype(resource.getURL(), resource.getLeft(), |
| resource.getTop(), resource.getWidth(), resource.getHeight()); |
| } |
| |
| /** |
| * Transforms an existing {@link Image} into the image represented by this |
| * prototype. |
| * |
| * @param image the instance to be transformed to match this prototype |
| */ |
| public abstract void applyTo(Image image); |
| |
| /** |
| * Transforms an existing {@link ImagePrototypeElement} into the image |
| * represented by this prototype. |
| * |
| * @param imageElement an <code>ImagePrototypeElement</code> created by |
| * {@link #createElement()} |
| */ |
| public void applyTo(ImagePrototypeElement imageElement) { |
| // Because this is a new method on an existing base class, we need to throw |
| // UnsupportedOperationException to avoid static errors. |
| throw new UnsupportedOperationException(); |
| } |
| |
| /** |
| * Creates a new {@link Element} based on the image represented by this |
| * prototype. The DOM structure may not necessarily a simple |
| * <code><img></code> element. It may be a more complex structure that |
| * should be treated opaquely. |
| * |
| * @return the <code>ImagePrototypeElement</code> corresponding to the image |
| * represented by this prototype |
| */ |
| public ImagePrototypeElement createElement() { |
| // Because this is a new method on an existing base class, we need to throw |
| // UnsupportedOperationException to avoid static errors. |
| throw new UnsupportedOperationException(); |
| } |
| |
| /** |
| * Creates a new {@link Image} instance based on the image represented by this |
| * prototype. |
| * |
| * @return a new {@link Image} based on this prototype |
| */ |
| public abstract Image createImage(); |
| |
| /** |
| * Gets an HTML fragment that displays the image represented by this |
| * prototype. The HTML returned is not necessarily a simple |
| * <code><img></code> element. It may be a more complex structure that |
| * should be treated opaquely. |
| * |
| * @return the HTML representation of this prototype |
| */ |
| public abstract String getHTML(); |
| } |