org.eclipse.jface.viewers.IBaseLabelProvider Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.jface Show documentation
This is org.eclipse.jface jar used by Scout SDK
The newest version!
/*******************************************************************************
 * Copyright (c) 2000, 2013 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 ILabelProvider or
 * an ITableLabelProvider.
 * 
 * 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.
 * 
 * 
 * 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 dispose
 * is called when the provider is no longer needed.
 * 
 *
 * @see ILabelProvider
 * @see ITableLabelProvider
 */
public interface IBaseLabelProvider {
    /**
     * Adds a listener to this label provider.
     * Has no effect if an identical listener is already registered.
     * 
     * Label provider listeners are informed about state changes
     * that affect the rendering of the viewer that uses this label provider.
     * 
     *
     * @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 true if the label would be affected,
     *    and false 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);
}