/*******************************************************************************
 * Copyright (c) 2000, 2006 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.viewers;

/**
 * A label provider maps an element of the viewer's model to
 * an optional image and optional text string used to display
 * the element in the viewer's control.  Certain label providers
 * may allow multiple labels per element.  
 * This is an "abstract interface", defining methods common 
 * to all label providers, but does not actually define the methods 
 * to get the label(s) for an element.  This interface should never
 * be directly implemented.
 * Most viewers will take either an <code>ILabelProvider</code> or
 * an <code>ITableLabelProvider</code>.
 * <p>
 * A label provider must not be shared between viewers 
 * since a label provider generally manages SWT resources (images),
 * which must be disposed when the viewer is disposed.
 * To simplify life cycle management, the current label provider 
 * of a viewer is disposed when the viewer is disposed.
 * </p>
 * <p>
 * Label providers can be used outside the context of viewers wherever
 * images are needed.  When label providers are used in this fashion
 * it is the responsibility of the user to ensure <code>dispose</code>
 * is called when the provider is no longer needed.
 * </p>
 *
 * @see ILabelProvider
 * @see ITableLabelProvider
 */
public interface IBaseLabelProvider {
    /**
     * Adds a listener to this label provider. 
     * Has no effect if an identical listener is already registered.
     * <p>
     * Label provider listeners are informed about state changes 
     * that affect the rendering of the viewer that uses this label provider.
     * </p>
     *
     * @param listener a label provider listener
     */
    public void addListener(ILabelProviderListener listener);

    /**
     * Disposes of this label provider.  When a label provider is
     * attached to a viewer, the viewer will automatically call
     * this method when the viewer is being closed.  When label providers
     * are used outside of the context of a viewer, it is the client's
     * responsibility to ensure that this method is called when the
     * provider is no longer needed.
     */
    public void dispose();

    /**
     * Returns whether the label would be affected 
     * by a change to the given property of the given element.
     * This can be used to optimize a non-structural viewer update.
     * If the property mentioned in the update does not affect the label,
     * then the viewer need not update the label.
     *
     * @param element the element
     * @param property the property
     * @return <code>true</code> if the label would be affected,
     *    and <code>false</code> if it would be unaffected
     */
    public boolean isLabelProperty(Object element, String property);

    /**
     * Removes a listener to this label provider.
     * Has no affect if an identical listener is not registered.
     *
     * @param listener a label provider listener
     */
    public void removeListener(ILabelProviderListener listener);
}