KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > google > gwt > user > client > ui > ImageBundle


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  * A tag interface that is used in the generation of image bundles. An image
20  * bundle is a composition of multiple images into a single large image, along
21  * with an interface for accessing a specific image's
22  * {@link com.google.gwt.user.client.ui.AbstractImagePrototype prototype} from
23  * within the composition. Obtain an image bundle instance by calling
24  * <code>GWT.create(<i>T</i>)</code>, where <code>T</code> is an
25  * interface that directly or indirectly extends <code>ImageBundle</code>.
26  *
27  * <p>
28  * To create and use an image bundle, extend the <code>ImageBundle</code>
29  * interface, and add a method declaration for each image that is to be part of
30  * the bundle. Each method must take no parameters and must have a return type
31  * of
32  * {@link com.google.gwt.user.client.ui.AbstractImagePrototype AbstractImagePrototype}.
33  * The image name can optionally be specified using the
34  * <code>gwt.resource</code> metadata tag. Valid image name extensions are
35  * <code>png</code>, <code>gif</code>, or <code>jpg</code>. If the
36  * image name contains '/' characters, it is assumed to be the name of a
37  * resource on the classpath, formatted as would be expected by
38  * <code>ClassLoader.getResource(String)</code>. Otherwise, the image must be
39  * located in the same package as the user-defined image bundle.
40  * </p>
41  *
42  * <p>
43  * The easiest way to create image bundle is to omit the
44  * <code>gwt.resource</code> metadata tag, and name the method the same as the
45  * image name, excluding the extension. When the image name is inferred in this
46  * manner, the image name's extension is assumed to be either <code>png</code>,
47  * <code>gif</code>, or <code>jpg</code>, and the image location must be
48  * in the same package as the user-defined image bundle. In the event that there
49  * are multiple image files that have the same name with different extensions,
50  * the order of extension precedence is <code>png</code>, <code>gif</code>,
51  * <code>jpg</code>.
52  *
53  * <h3>Example</h3>
54  *
55  * <pre class="code">
56  * public interface MyImageBundle extends ImageBundle {
57  *
58  * /**
59  * * Notice that the gwt.resource metadata tag is not present,
60  * * so the method name itself is assumed to match the associated
61  * * image filename.
62  * *
63  * * One of btn_submit_icon.png, btn_submit_icon.gif, or
64  * * btn_submit_icon.jpg must be located in the same package
65  * * as MyImageBundle.
66  * *&#47;
67  * public AbstractImagePrototype btn_submit_icon();
68  *
69  * // No doc comment is required if you want the default
70  * // name-matching behavior.
71  * public AbstractImagePrototype cancelButtonIcon();
72  * }
73  * </pre>
74  *
75  * </p>
76  *
77  * <p>
78  * An image bundle that uses the <code>gwt.resource</code> metadata tag to
79  * specify image names might look something like this:
80  *
81  * <pre class="code">
82  * public interface MyImageBundle extends ImageBundle {
83  *
84  * /**
85  * * The metadata tag contains no '/' characters, so
86  * * btn_submit_icon.gif must be located in the same
87  * * package as MyImageBundle.
88  * *
89  * * @gwt.resource btn_submit_icon.gif
90  * *&#47;
91  * public AbstractImagePrototype submitButtonIcon();
92  *
93  * /**
94  * * btn_cancel_icon.png must be located in the package
95  * * com.mycompany.myapp.icons (which must be on the classpath).
96  * *
97  * * @gwt.resource com/mycompany/myapp/icons/btn_cancel_icon.png
98  * *&#47;
99  * public AbstractImagePrototype cancelButtonIcon();
100  * }
101  * </pre>
102  *
103  * </p>
104  *
105  * <p>
106  * Here is how MyImageBundle might be used in an application:
107  *
108  * <pre class="code">
109  * ...
110  *
111  * // Create a new instance of MyImageBundle using GWT.create.
112  * // This only needs to be done once - a reference to myImageBundle can
113  * // be kept for use by other parts of the application.
114  * MyImageBundle myImageBundle = (MyImageBundle) GWT.create(MyImageBundle.class);
115  *
116  * // Retrieve the image prototypes from myImageBundle.
117  * AbstractImagePrototype submitButtonImgPrototype = myImageBundle.btn_submit_icon();
118  * AbstractImagePrototype cancelButtonImgPrototype = myImageBundle.cancelButtonIcon();
119  *
120  * // Add the images that are created based on the prototypes to the panel.
121  * panel.add(submitButtonImgPrototype.createImage());
122  * panel.add(cancelButtonImgPrototype.createImage());
123  *
124  * ...
125  * </pre>
126  *
127  * </p>
128  *
129  * <h3>For More Information</h3>
130  * See the GWT Developer Guide for an introduction to image bundles.
131  * @see com.google.gwt.user.client.ui.AbstractImagePrototype
132  * @see com.google.gwt.user.client.ui.Image#Image(String, int, int, int, int)
133  * @see com.google.gwt.user.client.ui.Image#setVisibleRect(int, int, int, int)
134  * @see com.google.gwt.user.client.ui.Image#setUrlAndVisibleRect(String, int,
135  * int, int, int)
136  */
137 public interface ImageBundle {
138 }
139
Popular Tags