01: /*
02: * Copyright 2007 Google Inc.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
05: * use this file except in compliance with the License. You may obtain a copy of
06: * the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
10: * Unless required by applicable law or agreed to in writing, software
11: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13: * License for the specific language governing permissions and limitations under
14: * the License.
15: */
16: package com.google.gwt.user.client.ui;
17:
18: /**
19: * An opaque representation of a particular image such that the image can be
20: * accessed either as an HTML fragment or as an {@link Image} object. An image
21: * prototype can be thought of as an abstract image factory with additional
22: * capabilities.
23: *
24: * <p>
25: * The {@link #applyTo(Image)} method provides an efficient way to replace the
26: * contents of an existing <code>Image</code>. This is useful in cases where
27: * an image changes its appearance based on a user's action. Instead of creating
28: * two <code>Image</code> objects then alternately hiding/showing them, one
29: * can use the {@link #applyTo(Image)} method of two
30: * <code>AbstractImagePrototype</code> objects to transform a single
31: * <code>Image</code> object between two (or more) visual representations. The
32: * use of <code>AbstractImagePrototypes</code> results in an cleaner and more
33: * efficient implementation.
34: * </p>
35: *
36: * <p>
37: * This class is also a useful way to encapsulate complex HTML that represents
38: * an image without actually instantiating <code>Image</code> objects. When
39: * constructing large HTML fragments, especially those that contain many images,
40: * {@link #getHTML()} can be much more efficient.
41: * </p>
42: */
43: public abstract class AbstractImagePrototype {
44:
45: /**
46: * Transforms an existing {@link Image} into the image represented by this
47: * prototype.
48: *
49: * @param image the instance to be transformed to match this prototype
50: */
51: public abstract void applyTo(Image image);
52:
53: /**
54: * Creates a new {@link Image} instance based on the image represented by this
55: * prototype.
56: *
57: * @return a new <code>Image</code> based on this prototype
58: */
59: public abstract Image createImage();
60:
61: /**
62: * Gets an HTML fragment that displays the image represented by this
63: * prototype. The HTML returned is not necessarily a simple
64: * <code><img></code> element. It may be a more complex structure that
65: * should be treated opaquely.
66: *
67: * @return the HTML representation of this prototype
68: */
69: public abstract String getHTML();
70: }
|