AbstractImagePrototype


1   /*
2    * Copyright 2007 Google Inc.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5    * use this file except in compliance with the License. You may obtain a copy of
6    * the License at
7    * 
8    * http://www.apache.org/licenses/LICENSE-2.0
9    * 
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   * protype 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>&lt;img&gt;</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  }
71
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags