View Javadoc

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 }