FieldDecorationRegistry


1   /*******************************************************************************
2    * Copyright (c) 2006, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jface.fieldassist;
12  
13  import java.util.HashMap  ;
14  import java.util.Iterator  ;
15  
16  import org.eclipse.jface.resource.ImageDescriptor;
17  import org.eclipse.jface.resource.ImageRegistry;
18  import org.eclipse.jface.resource.JFaceResources;
19  import org.eclipse.swt.graphics.Image;
20  
21  /**
22   * FieldDecorationRegistry is a common registry used to define shared field
23   * decorations within an application. Unlike resource registries, the
24   * FieldDecorationRegistry does not perform any lifecycle management of the
25   * decorations.
26   * </p>
27   * <p>
28   * Clients may specify images for the decorations in several different ways.
29   * Images may be described by their image id in a specified
30   * {@link ImageRegistry}. In this case, the life cycle of the image is managed
31   * by the image registry, and the decoration registry will not attempt to obtain
32   * an image from the image registry until the decoration is actually requested.
33   * In cases where the client has access to an already-created image, the image
34   * itself can be specified when registering the decoration. In this case, the
35   * life cycle should be managed by the specifying client.
36   * </p>
37   * 
38   * @see FieldDecoration
39   * @see ImageRegistry
40   * 
41   * @since 3.2
42   */
43  public class FieldDecorationRegistry {
44  
45      /**
46       * Decoration id for the decoration that should be used to cue the user that
47       * content proposals are available.
48       */
49      public static final String   DEC_CONTENT_PROPOSAL = "DEC_CONTENT_PROPOSAL"; //$NON-NLS-1$
50  
51      /**
52       * Decoration id for the decoration that should be used to cue the user that
53       * a field is required.
54       */
55      public static final String   DEC_REQUIRED = "DEC_REQUIRED"; //$NON-NLS-1$
56  
57      /**
58       * Decoration id for the decoration that should be used to cue the user that
59       * a field has an error.
60       */
61      public static final String   DEC_ERROR = "DEC_ERROR"; //$NON-NLS-1$
62  
63      /**
64       * Decoration id for the decoration that should be used to cue the user that
65       * a field has a warning.
66       */
67      public static final String   DEC_WARNING = "DEC_WARNING"; //$NON-NLS-1$
68  
69      /**
70       * Decoration id for the decoration that should be used to cue the user that
71       * a field has additional information.
72       * 
73       * @since 3.3
74       */
75      public static final String   DEC_INFORMATION = "DEC_INFORMATION"; //$NON-NLS-1$
76  
77      /**
78       * Decoration id for the decoration that should be used to cue the user that
79       * a field has an error with quick fix available.
80       * 
81       * @since 3.3
82       */
83      public static final String   DEC_ERROR_QUICKFIX = "DEC_ERRORQUICKFIX"; //$NON-NLS-1$
84  
85      /*
86       * Image id's
87       */
88      private static final String   IMG_DEC_FIELD_CONTENT_PROPOSAL = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_CONTENT_PROPOSAL"; //$NON-NLS-1$
89  
90      private static final String   IMG_DEC_FIELD_REQUIRED = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_REQUIRED"; //$NON-NLS-1$
91  
92      private static final String   IMG_DEC_FIELD_ERROR = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_ERROR"; //$NON-NLS-1$
93      
94      private static final String   IMG_DEC_FIELD_ERROR_QUICKFIX = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_ERROR_QUICKFIX"; //$NON-NLS-1$
95  
96      private static final String   IMG_DEC_FIELD_WARNING = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_WARNING"; //$NON-NLS-1$
97  
98      private static final String   IMG_DEC_FIELD_INFO = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_INFO"; //$NON-NLS-1$
99  
100     /*
101      * Declare images and decorations immediately.
102      */
103     static {
104         ImageRegistry imageRegistry = JFaceResources.getImageRegistry();
105 
106         // Define the images used in the standard decorations.
107         imageRegistry.put(IMG_DEC_FIELD_CONTENT_PROPOSAL, ImageDescriptor
108                 .createFromFile(FieldDecorationRegistry.class,
109                         "images/contassist_ovr.gif"));//$NON-NLS-1$
110         imageRegistry.put(IMG_DEC_FIELD_ERROR, ImageDescriptor.createFromFile(
111                 FieldDecorationRegistry.class, "images/error_ovr.gif"));//$NON-NLS-1$
112 
113         imageRegistry.put(IMG_DEC_FIELD_WARNING, ImageDescriptor
114                 .createFromFile(FieldDecorationRegistry.class,
115                         "images/warn_ovr.gif"));//$NON-NLS-1$
116 
117         imageRegistry.put(IMG_DEC_FIELD_REQUIRED, ImageDescriptor
118                 .createFromFile(FieldDecorationRegistry.class,
119                         "images/required_field_cue.gif"));//$NON-NLS-1$ 
120         
121         imageRegistry.put(IMG_DEC_FIELD_ERROR_QUICKFIX, ImageDescriptor
122                 .createFromFile(FieldDecorationRegistry.class,
123                         "images/errorqf_ovr.gif"));//$NON-NLS-1$
124         
125         imageRegistry.put(IMG_DEC_FIELD_INFO, ImageDescriptor
126                 .createFromFile(FieldDecorationRegistry.class,
127                         "images/info_ovr.gif"));//$NON-NLS-1$       
128 
129         // Define the standard decorations. Some do not have standard
130         // descriptions. Use null in these cases.
131         getDefault()
132                 .registerFieldDecoration(
133                         DEC_CONTENT_PROPOSAL,
134                         JFaceResources
135                                 .getString("FieldDecorationRegistry.contentAssistMessage"), //$NON-NLS-1$
136                         IMG_DEC_FIELD_CONTENT_PROPOSAL, imageRegistry);
137 
138         getDefault().registerFieldDecoration(
139                 DEC_ERROR,
140                 JFaceResources
141                         .getString("FieldDecorationRegistry.errorMessage"), //$NON-NLS-1$
142                 IMG_DEC_FIELD_ERROR, imageRegistry);
143         
144         getDefault().registerFieldDecoration(
145                 DEC_ERROR_QUICKFIX,
146                 JFaceResources
147                         .getString("FieldDecorationRegistry.errorQuickFixMessage"), //$NON-NLS-1$
148                 IMG_DEC_FIELD_ERROR_QUICKFIX, imageRegistry);
149 
150         getDefault().registerFieldDecoration(DEC_WARNING, null,
151                 IMG_DEC_FIELD_WARNING, imageRegistry);
152         
153         getDefault().registerFieldDecoration(DEC_INFORMATION, null,
154                 IMG_DEC_FIELD_INFO, imageRegistry);
155 
156         getDefault()
157                 .registerFieldDecoration(
158                         DEC_REQUIRED,
159                         JFaceResources
160                                 .getString("FieldDecorationRegistry.requiredFieldMessage"), //$NON-NLS-1$
161                         IMG_DEC_FIELD_REQUIRED, imageRegistry);
162 
163     }
164 
165     /*
166      * Data structure that holds onto the decoration image info and description,
167      * and can produce a decorator on request.
168      */
169     class Entry {
170         private String   description;
171 
172         private String   imageId;
173 
174         private ImageRegistry imageRegistry;
175 
176         private Image image;
177 
178         private FieldDecoration decoration;
179 
180         Entry(String   description, String   imageId, ImageRegistry registry) {
181             this.description = description;
182             this.imageId = imageId;
183             this.imageRegistry = registry;
184         }
185 
186         Entry(String   description, Image image) {
187             this.description = description;
188             this.image = image;
189         }
190 
191         FieldDecoration getDecoration() {
192             if (decoration == null) {
193                 if (image == null) {
194                     if (imageRegistry == null) {
195                         imageRegistry = JFaceResources.getImageRegistry();
196                     }
197                     image = imageRegistry.get(imageId);
198                 }
199                 decoration = new FieldDecoration(image, description);
200             }
201             // Null out all other fields now that the decoration has an image
202             description = null;
203             imageId = null;
204             imageRegistry = null;
205             image = null;
206 
207             return decoration;
208         }
209     }
210 
211     /**
212      * Default instance of the registry. Applications may install their own
213      * registry.
214      */
215     private static FieldDecorationRegistry defaultInstance;
216 
217     /**
218      * Maximum width and height used by decorations in this registry. Clients
219      * may use these values to reserve space in dialogs for decorations or to
220      * adjust layouts so that decorated and non-decorated fields line up.
221      */
222     private int maxDecorationWidth = 0;
223     private int maxDecorationHeight = 0;
224 
225     private HashMap   /* <String id, FieldDecoration> */decorations = new HashMap  ();
226 
227     /**
228      * Get the default FieldDecorationRegistry.
229      * 
230      * @return the singleton FieldDecorationRegistry that is used to manage
231      *         shared field decorations.
232      */
233     public static FieldDecorationRegistry getDefault() {
234         if (defaultInstance == null) {
235             defaultInstance = new FieldDecorationRegistry();
236         }
237         return defaultInstance;
238     }
239 
240     /**
241      * Set the default FieldDecorationRegistry.
242      * 
243      * @param defaultRegistry
244      *            the singleton FieldDecorationRegistry that is used to manage
245      *            shared field decorations.
246      */
247     public static void setDefault(FieldDecorationRegistry defaultRegistry) {
248         defaultInstance = defaultRegistry;
249     }
250 
251     /**
252      * Construct a FieldDecorationRegistry.
253      */
254     public FieldDecorationRegistry() {
255         maxDecorationWidth = 0;
256         maxDecorationHeight = 0;
257     }
258 
259     /**
260      * Get the maximum width (in pixels) of any decoration retrieved so far in
261      * the registry. This value changes as decorations are added and retrieved.
262      * This value can be used by clients to reserve space or otherwise compute
263      * margins when aligning non-decorated fields with decorated fields.
264      * 
265      * @return the maximum width in pixels of any accessed decoration
266      */
267     public int getMaximumDecorationWidth() {
268         return maxDecorationWidth;
269     }
270 
271     /**
272      * Get the maximum height (in pixels) of any decoration retrieved so far in
273      * the registry. This value changes as decorations are added and retrieved.
274      * This value can be used by clients to reserve space or otherwise compute
275      * margins when aligning non-decorated fields with decorated fields.
276      * 
277      * 
278      * @return the maximum height in pixels of any accessed decoration
279      */
280     public int getMaximumDecorationHeight() {
281         return maxDecorationHeight;
282     }
283 
284     /**
285      * Registers a field decoration using the specified id. The lifecyle of the
286      * supplied image should be managed by the client. That is, it will never be
287      * disposed by this registry and the decoration should be removed from the
288      * registry if the image is ever disposed elsewhere.
289      * 
290      * @param id
291      *            the String id used to identify and access the decoration.
292      * @param description
293      *            the String description to be used in the decoration, or
294      *            <code>null</code> if the decoration has no description.
295      * @param image
296      *            the image to be used in the decoration
297      */
298     public void registerFieldDecoration(String   id, String   description,
299             Image image) {
300         decorations.put(id, new Entry(description, image));
301         // Recompute the maximums since this might be a replacement
302         recomputeMaximums();
303     }
304 
305     /**
306      * Registers a field decoration using the specified id. An image id of an
307      * image located in the default JFaceResources image registry is supplied.
308      * The image will not be created until the decoration is requested.
309      * 
310      * @param id
311      *            the String id used to identify and access the decoration.
312      * @param description
313      *            the String description to be used in the decoration, or
314      *            <code>null</code> if the decoration has no description. *
315      * @param imageId
316      *            the id of the image in the JFaceResources image registry that
317      *            is used for this decorator
318      */
319     public void registerFieldDecoration(String   id, String   description,
320             String   imageId) {
321         decorations.put(id, new Entry(description, imageId, JFaceResources
322                 .getImageRegistry()));
323         // Recompute the maximums as this could be a replacement of a previous
324         // image.
325         recomputeMaximums();
326     }
327 
328     /**
329      * Registers a field decoration using the specified id. An image id and an
330      * image registry are supplied. The image will not be created until the
331      * decoration is requested.
332      * 
333      * @param id
334      *            the String id used to identify and access the decoration.
335      * @param description
336      *            the String description to be used in the decoration, or
337      *            <code>null</code> if the decoration has no description. *
338      * @param imageId
339      *            the id of the image in the supplied image registry that is
340      *            used for this decorator
341      * @param imageRegistry
342      *            the registry used to obtain the image
343      */
344     public void registerFieldDecoration(String   id, String   description,
345             String   imageId, ImageRegistry imageRegistry) {
346         decorations.put(id, new Entry(description, imageId, imageRegistry));
347         // Recompute the maximums since this could be a replacement
348         recomputeMaximums();
349     }
350 
351     /**
352      * Unregisters the field decoration with the specified id. No lifecycle
353      * management is performed on the decoration's image. This message has no
354      * effect if no field decoration with the specified id was previously
355      * registered.
356      * </p>
357      * <p>
358      * This method need not be called if the registered decoration's image is
359      * managed in an image registry. In that case, leaving the decoration in the
360      * registry will do no harm since the image will remain valid and will be
361      * properly disposed when the application is shut down. This method should
362      * be used in cases where the caller intends to dispose of the image
363      * referred to by the decoration, or otherwise determines that the
364      * decoration should no longer be used.
365      * 
366      * @param id
367      *            the String id of the decoration to be unregistered.
368      */
369     public void unregisterFieldDecoration(String   id) {
370         decorations.remove(id);
371         recomputeMaximums();
372     }
373 
374     /**
375      * Returns the field decoration registered by the specified id .
376      * 
377      * @param id
378      *            the String id used to access the decoration.
379      * @return the FieldDecoration with the specified id, or <code>null</code>
380      *         if there is no decoration with the specified id.
381      */
382     public FieldDecoration getFieldDecoration(String   id) {
383         Object   entry = decorations.get(id);
384         if (entry == null) {
385             return null;
386         }
387         return ((Entry) entry).getDecoration();
388 
389     }
390 
391     /*
392      * The maximum decoration width and height must be recomputed. Typically
393      * called in response to adding, removing, or replacing a decoration.
394      */
395     private void recomputeMaximums() {
396         Iterator   entries = decorations.values().iterator();
397         
398         maxDecorationHeight = 0;
399         maxDecorationWidth = 0;
400         while (entries.hasNext()) {
401             Image image = ((Entry)entries.next()).getDecoration().getImage();
402             if (image != null) {
403                 maxDecorationHeight = Math.max(maxDecorationHeight, image.getBounds().height);
404                 maxDecorationWidth = Math.max(maxDecorationWidth, image.getBounds().width);
405             }
406         }
407 
408     }
409 }
410
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags