1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.myfaces.trinidad.skin;
20
21 import java.io.IOException;
22 import java.io.InputStream;
23
24 import java.util.Map;
25 import javax.faces.context.FacesContext;
26
27 import org.apache.myfaces.trinidad.context.RenderingContext;
28 import org.apache.myfaces.trinidad.logging.TrinidadLogger;
29
30
31 /**
32 * An object which represents a customizable icon that is capable of
33 * rendering itself. Icons objects are registered with a Skin
34 * via the Skin.registerIcon() method and are retrieved by Renderers
35 * via Skin.getIcon(). Customizers can override icons declaratively
36 *in the skin css file.
37 * <p>
38 * Icon implementations which are capable of providing an image
39 * representation of the icon should override getImageURI(), getImageWidth()
40 * and getImageHeight(). The default implementations of these methods
41 * return null, which is an acceptable default for Icons which do
42 * not make use of images (ie. for text-based Icon implementations).
43 *
44 * @version $Name: $ ($Revision: adfrt/faces/adf-faces-impl/src/main/java/oracle/adfinternal/view/faces/skin/icon/Icon.java#0 $) $Date: 10-nov-2005.18:59:03 $
45 */
46 abstract public class Icon
47 {
48 // keys that can be used in the attribute Map in renderIcon
49 public static final String SHORT_DESC_KEY = "shortDesc";
50 public static final String ALIGN_KEY = "align";
51 public static final String WIDTH_KEY = "width";
52 public static final String HEIGHT_KEY = "height";
53 public static final String EMBEDDED_KEY = "embedded";
54 public static final String ID_KEY = "id";
55 public static final String STYLE_CLASS_KEY = "styleClass";
56 public static final String INLINE_STYLE_KEY = "inlineStyle";
57
58 /**
59 * Renders the Icon.
60 *
61 * @param context FacesContext
62 * @param arc The RenderingContext for the
63 * current request.
64 * @param attrs A Map which which provides access to
65 * values that might be useful to Icon implementations,
66 * such as "id" and "shortDesc".
67 */
68 abstract public void renderIcon(
69 FacesContext context,
70 RenderingContext arc,
71 Map<String, ? extends Object> attrs
72 ) throws IOException;
73
74 /**
75 * Returns a URI to the image that is used as the icon's content.
76 * The default implementation of this method simply returns null,
77 * which indicates to the caller that no image representation of
78 * the Icon is available.
79 * @param context FacesContext
80 * @param arc The RenderingContext for the
81 * current request.
82 */
83 public Object getImageURI(
84 FacesContext context,
85 RenderingContext arc)
86 {
87 return null;
88 }
89
90 /**
91 * Returns the width of the image.
92 * The default implementation of this method simply returns null,
93 * which indicates to the caller the width of the image is not
94 * known - or that the Icon does not provide an image representation.
95 * @param arc RenderingContext
96 */
97 public Integer getImageWidth(RenderingContext arc)
98 {
99 return null;
100 }
101
102 /**
103 * Returns the height of the image.
104 * The default implementation of this method simply returns null,
105 * which indicates to the caller the height of the image is not
106 * known - or that the Icon does not provide an image representation.
107 * @param arc RenderingContext
108 *
109 */
110 public Integer getImageHeight(RenderingContext arc)
111 {
112 return null;
113 }
114
115 /**
116 * Returns an InputStream which provides access to the
117 * image data for image-based Icons.
118 * @param context FacesContext
119 * @param arc The RenderingContext for the
120 * current request.
121 */
122 // TODO: Delete if unnecessary
123 public InputStream openStream(
124 FacesContext context,
125 RenderingContext arc
126 ) throws IOException
127 {
128 // This operation is not supported by default. Log a warning.
129 if (_LOG.isWarning())
130 _LOG.warning("UNABLE_RETRIEVE_IMAGE_DATA", getClass().getName());
131
132 return null;
133 }
134
135 /**
136 * Returns true if the icon is non-existent, and will render no content
137 * at all.
138 */
139 public boolean isNull()
140 {
141 return false;
142 }
143
144 private static final TrinidadLogger _LOG = TrinidadLogger.createTrinidadLogger(Icon.class);
145
146 }