/*******************************************************************************
 * Copyright (c) 2000, 2013 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * 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 effect if an identical listener is not registered.
	 *
	 * @param listener a label provider listener
	 */
	public void removeListener(ILabelProviderListener listener);
}
