/*******************************************************************************
* Copyright (c) 2009, 2015 Oakland Software Incorporated 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:
* Oakland Software Incorporated - initial API and implementation
******************************************************************************/
package org.eclipse.ui.navigator;
import org.eclipse.swt.widgets.Item;
/**
* Allows improved performance by optimizing label updates of the CommonViewer.
*
* Often label updates come in the form of resource updates, and the resources
* themselves are not directly stored in the {@link CommonViewer}; instead other model
* objects are stored. In addition, it may be the case where the objects that
* have changed are not present in the Tree associated with the CommonViewer
* because they have not been opened or expanded.
*
* You can use an instance of this class to define a mapping between the current
* Tree Items associated with the CommonViewer and the (typically resource) objects
* where a change is notified. The change is notified to the
* {@link CommonViewer#handleLabelProviderChanged(org.eclipse.jface.viewers.LabelProviderChangedEvent)}.
*
* The mapper object (implementing this interface) is associated with the CommonViewer using
* the {@link CommonViewer#setMapper(ICommonViewerMapper)} method.
*
* When this mapper wishes to update the CommonViewer, the
* {@link CommonViewer#doUpdateItem(org.eclipse.swt.widgets.Widget)}
* method is used.
*
* @since 3.4
* @noextend This interface is not intended to be extended by clients.
*
*/
public interface ICommonViewerMapper {
/**
* Adds a new item to the map. Called by the {@link CommonViewer} when the element is
* added to the Tree.
*
* @param element Element to map
* @param item The item used for the element
*/
public void addToMap(Object element, Item item);
/**
* Removes an element from the map. Called by the {@link CommonViewer} when the element is
* removed from the Tree.
*
* @param element The data element
* @param item The table or tree item
*/
public void removeFromMap(Object element, Item item);
/**
* Clears the map.
*/
public void clearMap();
/**
* Tests if the map is empty
* @return Returns if there are mappings
*/
public boolean isEmpty();
/**
* Tests if this mapper handles the specified object. This is used only
* by the viewer to determine if the object should be looked up in the mapper.
* This is not to be used when the object is being added to the mapper, as
* the mapper may adapt to the desired object to be mapped (like adapting
* from a Java model object to a resource object for example).
*
* @param object the object that the mapper can handle
* @return true if it does
*/
public boolean handlesObject(Object object);
/**
* Indicates the specified object has changed. If the object
* has a corresponding Item in the map, the associated {@link CommonViewer}
* is notified of the change using the {@link CommonViewer#doUpdateItem(org.eclipse.swt.widgets.Widget)}
* method so that it can update its state.
*
* @param object the object that changed
*/
public void objectChanged(Object object);
}