FieldDecorationRegistry.java :  » IDE-Eclipse » jface » org » eclipse » jface » fieldassist » Java Open Source

Java Open Source » IDE Eclipse » jface 
jface » org » eclipse » jface » fieldassist » FieldDecorationRegistry.java
/*******************************************************************************
 * Copyright (c) 2006, 2007 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.fieldassist;

import java.util.HashMap;
import java.util.Iterator;

import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.jface.resource.ImageRegistry;
import org.eclipse.jface.resource.JFaceResources;
import org.eclipse.swt.graphics.Image;

/**
 * FieldDecorationRegistry is a common registry used to define shared field
 * decorations within an application. Unlike resource registries, the
 * FieldDecorationRegistry does not perform any lifecycle management of the
 * decorations.
 * </p>
 * <p>
 * Clients may specify images for the decorations in several different ways.
 * Images may be described by their image id in a specified
 * {@link ImageRegistry}. In this case, the life cycle of the image is managed
 * by the image registry, and the decoration registry will not attempt to obtain
 * an image from the image registry until the decoration is actually requested.
 * In cases where the client has access to an already-created image, the image
 * itself can be specified when registering the decoration. In this case, the
 * life cycle should be managed by the specifying client.
 * </p>
 * 
 * @see FieldDecoration
 * @see ImageRegistry
 * 
 * @since 3.2
 */
public class FieldDecorationRegistry {

  /**
   * Decoration id for the decoration that should be used to cue the user that
   * content proposals are available.
   */
  public static final String DEC_CONTENT_PROPOSAL = "DEC_CONTENT_PROPOSAL"; //$NON-NLS-1$

  /**
   * Decoration id for the decoration that should be used to cue the user that
   * a field is required.
   */
  public static final String DEC_REQUIRED = "DEC_REQUIRED"; //$NON-NLS-1$

  /**
   * Decoration id for the decoration that should be used to cue the user that
   * a field has an error.
   */
  public static final String DEC_ERROR = "DEC_ERROR"; //$NON-NLS-1$

  /**
   * Decoration id for the decoration that should be used to cue the user that
   * a field has a warning.
   */
  public static final String DEC_WARNING = "DEC_WARNING"; //$NON-NLS-1$

  /**
   * Decoration id for the decoration that should be used to cue the user that
   * a field has additional information.
   * 
   * @since 3.3
   */
  public static final String DEC_INFORMATION = "DEC_INFORMATION"; //$NON-NLS-1$

  /**
   * Decoration id for the decoration that should be used to cue the user that
   * a field has an error with quick fix available.
   * 
   * @since 3.3
   */
  public static final String DEC_ERROR_QUICKFIX = "DEC_ERRORQUICKFIX"; //$NON-NLS-1$

  /*
   * Image id's
   */
  private static final String IMG_DEC_FIELD_CONTENT_PROPOSAL = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_CONTENT_PROPOSAL"; //$NON-NLS-1$

  private static final String IMG_DEC_FIELD_REQUIRED = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_REQUIRED"; //$NON-NLS-1$

  private static final String IMG_DEC_FIELD_ERROR = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_ERROR"; //$NON-NLS-1$
  
  private static final String IMG_DEC_FIELD_ERROR_QUICKFIX = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_ERROR_QUICKFIX"; //$NON-NLS-1$

  private static final String IMG_DEC_FIELD_WARNING = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_WARNING"; //$NON-NLS-1$

  private static final String IMG_DEC_FIELD_INFO = "org.eclipse.jface.fieldassist.IMG_DEC_FIELD_INFO"; //$NON-NLS-1$

  /*
   * Declare images and decorations immediately.
   */
  static {
    ImageRegistry imageRegistry = JFaceResources.getImageRegistry();

    // Define the images used in the standard decorations.
    imageRegistry.put(IMG_DEC_FIELD_CONTENT_PROPOSAL, ImageDescriptor
        .createFromFile(FieldDecorationRegistry.class,
            "images/contassist_ovr.gif"));//$NON-NLS-1$
    imageRegistry.put(IMG_DEC_FIELD_ERROR, ImageDescriptor.createFromFile(
        FieldDecorationRegistry.class, "images/error_ovr.gif"));//$NON-NLS-1$

    imageRegistry.put(IMG_DEC_FIELD_WARNING, ImageDescriptor
        .createFromFile(FieldDecorationRegistry.class,
            "images/warn_ovr.gif"));//$NON-NLS-1$

    imageRegistry.put(IMG_DEC_FIELD_REQUIRED, ImageDescriptor
        .createFromFile(FieldDecorationRegistry.class,
            "images/required_field_cue.gif"));//$NON-NLS-1$  
    
    imageRegistry.put(IMG_DEC_FIELD_ERROR_QUICKFIX, ImageDescriptor
        .createFromFile(FieldDecorationRegistry.class,
            "images/errorqf_ovr.gif"));//$NON-NLS-1$
    
    imageRegistry.put(IMG_DEC_FIELD_INFO, ImageDescriptor
        .createFromFile(FieldDecorationRegistry.class,
            "images/info_ovr.gif"));//$NON-NLS-1$    

    // Define the standard decorations. Some do not have standard
    // descriptions. Use null in these cases.
    getDefault()
        .registerFieldDecoration(
            DEC_CONTENT_PROPOSAL,
            JFaceResources
                .getString("FieldDecorationRegistry.contentAssistMessage"), //$NON-NLS-1$
            IMG_DEC_FIELD_CONTENT_PROPOSAL, imageRegistry);

    getDefault().registerFieldDecoration(
        DEC_ERROR,
        JFaceResources
            .getString("FieldDecorationRegistry.errorMessage"), //$NON-NLS-1$
        IMG_DEC_FIELD_ERROR, imageRegistry);
    
    getDefault().registerFieldDecoration(
        DEC_ERROR_QUICKFIX,
        JFaceResources
            .getString("FieldDecorationRegistry.errorQuickFixMessage"), //$NON-NLS-1$
        IMG_DEC_FIELD_ERROR_QUICKFIX, imageRegistry);

    getDefault().registerFieldDecoration(DEC_WARNING, null,
        IMG_DEC_FIELD_WARNING, imageRegistry);
    
    getDefault().registerFieldDecoration(DEC_INFORMATION, null,
        IMG_DEC_FIELD_INFO, imageRegistry);

    getDefault()
        .registerFieldDecoration(
            DEC_REQUIRED,
            JFaceResources
                .getString("FieldDecorationRegistry.requiredFieldMessage"), //$NON-NLS-1$
            IMG_DEC_FIELD_REQUIRED, imageRegistry);

  }

  /*
   * Data structure that holds onto the decoration image info and description,
   * and can produce a decorator on request.
   */
  class Entry {
    private String description;

    private String imageId;

    private ImageRegistry imageRegistry;

    private Image image;

    private FieldDecoration decoration;

    Entry(String description, String imageId, ImageRegistry registry) {
      this.description = description;
      this.imageId = imageId;
      this.imageRegistry = registry;
    }

    Entry(String description, Image image) {
      this.description = description;
      this.image = image;
    }

    FieldDecoration getDecoration() {
      if (decoration == null) {
        if (image == null) {
          if (imageRegistry == null) {
            imageRegistry = JFaceResources.getImageRegistry();
          }
          image = imageRegistry.get(imageId);
        }
        decoration = new FieldDecoration(image, description);
      }
      // Null out all other fields now that the decoration has an image
      description = null;
      imageId = null;
      imageRegistry = null;
      image = null;

      return decoration;
    }
  }

  /**
   * Default instance of the registry. Applications may install their own
   * registry.
   */
  private static FieldDecorationRegistry defaultInstance;

  /**
   * Maximum width and height used by decorations in this registry. Clients
   * may use these values to reserve space in dialogs for decorations or to
   * adjust layouts so that decorated and non-decorated fields line up.
   */
  private int maxDecorationWidth = 0;
  private int maxDecorationHeight = 0;

  private HashMap /* <String id, FieldDecoration> */decorations = new HashMap();

  /**
   * Get the default FieldDecorationRegistry.
   * 
   * @return the singleton FieldDecorationRegistry that is used to manage
   *         shared field decorations.
   */
  public static FieldDecorationRegistry getDefault() {
    if (defaultInstance == null) {
      defaultInstance = new FieldDecorationRegistry();
    }
    return defaultInstance;
  }

  /**
   * Set the default FieldDecorationRegistry.
   * 
   * @param defaultRegistry
   *            the singleton FieldDecorationRegistry that is used to manage
   *            shared field decorations.
   */
  public static void setDefault(FieldDecorationRegistry defaultRegistry) {
    defaultInstance = defaultRegistry;
  }

  /**
   * Construct a FieldDecorationRegistry.
   */
  public FieldDecorationRegistry() {
    maxDecorationWidth = 0;
    maxDecorationHeight = 0;
  }

  /**
   * Get the maximum width (in pixels) of any decoration retrieved so far in
   * the registry. This value changes as decorations are added and retrieved.
   * This value can be used by clients to reserve space or otherwise compute
   * margins when aligning non-decorated fields with decorated fields.
   * 
   * @return the maximum width in pixels of any accessed decoration
   */
  public int getMaximumDecorationWidth() {
    return maxDecorationWidth;
  }

  /**
   * Get the maximum height (in pixels) of any decoration retrieved so far in
   * the registry. This value changes as decorations are added and retrieved.
   * This value can be used by clients to reserve space or otherwise compute
   * margins when aligning non-decorated fields with decorated fields.
   * 
   * 
   * @return the maximum height in pixels of any accessed decoration
   */
  public int getMaximumDecorationHeight() {
    return maxDecorationHeight;
  }

  /**
   * Registers a field decoration using the specified id. The lifecyle of the
   * supplied image should be managed by the client. That is, it will never be
   * disposed by this registry and the decoration should be removed from the
   * registry if the image is ever disposed elsewhere.
   * 
   * @param id
   *            the String id used to identify and access the decoration.
   * @param description
   *            the String description to be used in the decoration, or
   *            <code>null</code> if the decoration has no description.
   * @param image
   *            the image to be used in the decoration
   */
  public void registerFieldDecoration(String id, String description,
      Image image) {
    decorations.put(id, new Entry(description, image));
    // Recompute the maximums since this might be a replacement
    recomputeMaximums();
  }

  /**
   * Registers a field decoration using the specified id. An image id of an
   * image located in the default JFaceResources image registry is supplied.
   * The image will not be created until the decoration is requested.
   * 
   * @param id
   *            the String id used to identify and access the decoration.
   * @param description
   *            the String description to be used in the decoration, or
   *            <code>null</code> if the decoration has no description. *
   * @param imageId
   *            the id of the image in the JFaceResources image registry that
   *            is used for this decorator
   */
  public void registerFieldDecoration(String id, String description,
      String imageId) {
    decorations.put(id, new Entry(description, imageId, JFaceResources
        .getImageRegistry()));
    // Recompute the maximums as this could be a replacement of a previous
    // image.
    recomputeMaximums();
  }

  /**
   * Registers a field decoration using the specified id. An image id and an
   * image registry are supplied. The image will not be created until the
   * decoration is requested.
   * 
   * @param id
   *            the String id used to identify and access the decoration.
   * @param description
   *            the String description to be used in the decoration, or
   *            <code>null</code> if the decoration has no description. *
   * @param imageId
   *            the id of the image in the supplied image registry that is
   *            used for this decorator
   * @param imageRegistry
   *            the registry used to obtain the image
   */
  public void registerFieldDecoration(String id, String description,
      String imageId, ImageRegistry imageRegistry) {
    decorations.put(id, new Entry(description, imageId, imageRegistry));
    // Recompute the maximums since this could be a replacement
    recomputeMaximums();
  }

  /**
   * Unregisters the field decoration with the specified id. No lifecycle
   * management is performed on the decoration's image. This message has no
   * effect if no field decoration with the specified id was previously
   * registered.
   * </p>
   * <p>
   * This method need not be called if the registered decoration's image is
   * managed in an image registry. In that case, leaving the decoration in the
   * registry will do no harm since the image will remain valid and will be
   * properly disposed when the application is shut down. This method should
   * be used in cases where the caller intends to dispose of the image
   * referred to by the decoration, or otherwise determines that the
   * decoration should no longer be used.
   * 
   * @param id
   *            the String id of the decoration to be unregistered.
   */
  public void unregisterFieldDecoration(String id) {
    decorations.remove(id);
    recomputeMaximums();
  }

  /**
   * Returns the field decoration registered by the specified id .
   * 
   * @param id
   *            the String id used to access the decoration.
   * @return the FieldDecoration with the specified id, or <code>null</code>
   *         if there is no decoration with the specified id.
   */
  public FieldDecoration getFieldDecoration(String id) {
    Object entry = decorations.get(id);
    if (entry == null) {
      return null;
    }
    return ((Entry) entry).getDecoration();

  }

  /*
   * The maximum decoration width and height must be recomputed. Typically
   * called in response to adding, removing, or replacing a decoration.
   */
  private void recomputeMaximums() {
    Iterator entries = decorations.values().iterator();
    
    maxDecorationHeight = 0;
    maxDecorationWidth = 0;
    while (entries.hasNext()) {
      Image image = ((Entry)entries.next()).getDecoration().getImage();
      if (image != null) {
        maxDecorationHeight = Math.max(maxDecorationHeight, image.getBounds().height);
        maxDecorationWidth = Math.max(maxDecorationWidth, image.getBounds().width);
      }
    }

  }
}
java2s.com  | Contact Us | Privacy Policy
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.