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

Go to download
/*******************************************************************************
 * Copyright (c) 2000, 2019 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
 *     Tom Schindl - bug 151205
 *     Lars Vogel  - Bug 402439, 475689
 *     Thorsten Maack  - Bug 482163
 *     Jan-Ove Weichel  - Bug 481490
 *     Alexander Fedorov  - Bug 548314
 *******************************************************************************/
package org.eclipse.jface.viewers;

import static org.eclipse.swt.events.SelectionListener.widgetSelectedAdapter;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Iterator;
import java.util.List;

import org.eclipse.core.runtime.Assert;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.ListenerList;
import org.eclipse.core.runtime.Status;
import org.eclipse.jface.internal.InternalPolicy;
import org.eclipse.jface.util.OpenStrategy;
import org.eclipse.jface.util.Policy;
import org.eclipse.jface.util.SafeRunnable;
import org.eclipse.swt.SWT;
import org.eclipse.swt.dnd.DragSource;
import org.eclipse.swt.dnd.DragSourceListener;
import org.eclipse.swt.dnd.DropTarget;
import org.eclipse.swt.dnd.DropTargetListener;
import org.eclipse.swt.dnd.Transfer;
import org.eclipse.swt.events.DisposeEvent;
import org.eclipse.swt.events.SelectionEvent;
import org.eclipse.swt.events.SelectionListener;
import org.eclipse.swt.graphics.Color;
import org.eclipse.swt.graphics.Font;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Item;
import org.eclipse.swt.widgets.TableItem;
import org.eclipse.swt.widgets.TreeItem;
import org.eclipse.swt.widgets.Widget;

/**
 * Abstract base implementation for structure-oriented viewers (trees, lists,
 * tables). Supports custom sorting, filtering, and rendering.
 * 
 * Any number of viewer filters can be added to this viewer (using
 * addFilter). When the viewer receives an update, it asks each
 * of its filters if it is out of date, and refilters elements as required.
 * 
 *
 * @see ViewerFilter
 * @see ViewerComparator
 */
public abstract class StructuredViewer extends ContentViewer implements IPostSelectionProvider {

	/**
	 * A map from the viewer's model elements to SWT widgets. (key type:
	 * Object, value type: Widget, or Widget[]).
	 * null means that the element map is disabled.
	 */
	private CustomHashtable elementMap;

	/**
	 * The comparer to use for comparing elements, or null to use
	 * the default equals and hashCode methods on
	 * the element itself.
	 */
	private IElementComparer comparer;

	/**
	 * This viewer's comparator used for sorting. null means there is no comparator.
	 */
	private ViewerComparator sorter;

	/**
	 * This viewer's filters (element type: ViewerFilter).
	 * null means there are no filters.
	 */
	private List filters;

	/**
	 * Indicates whether the viewer should attempt to preserve the selection
	 * across update operations.
	 *
	 * @see #setSelection(ISelection, boolean)
	 */
	private boolean preserveSelection = true;

	/**
	 * Indicates whether a selection change is in progress on this viewer.
	 *
	 * @see #setSelection(ISelection, boolean)
	 */
	private boolean inChange;

	/**
	 * Used while a selection change is in progress on this viewer to indicates
	 * whether the selection should be restored.
	 *
	 * @see #setSelection(ISelection, boolean)
	 */
	private boolean restoreSelection;

	/**
	 * List of double-click state listeners (element type:
	 * IDoubleClickListener).
	 *
	 * @see #fireDoubleClick
	 */
	private ListenerList doubleClickListeners = new ListenerList<>();

	/**
	 * List of open listeners (element type:
	 * ISelectionActivateListener).
	 *
	 * @see #fireOpen
	 */
	private ListenerList openListeners = new ListenerList<>();

	/**
	 * List of post selection listeners (element type:
	 * ISelectionActivateListener).
	 *
	 * @see #firePostSelectionChanged
	 */
	private ListenerList postSelectionChangedListeners = new ListenerList<>();

	/**
	 * The colorAndFontCollector is an object used by viewers that
	 * support the IColorProvider, the IFontProvider and/or the
	 * IViewerLabelProvider for color and font updates.
	 * Initialize it to have no color or font providing
	 * initially.
	 * @since 3.1
	 */
	private ColorAndFontCollector colorAndFontCollector = new ColorAndFontCollector();


	/**
	 * Calls when associate() and disassociate() are called
	 */
	private StructuredViewerInternals.AssociateListener associateListener;

	/**
	 * Empty array of widgets.
	 */
	private static Widget[] NO_WIDGETS = new Widget[0];

	/**
	 * The ColorAndFontCollector is a helper class for viewers
	 * that have color and font support ad optionally decorators.
	 * @see IColorDecorator
	 * @see IFontDecorator
	 * @see IColorProvider
	 * @see IFontProvider
	 * @see IDecoration
	 */
	protected class ColorAndFontCollectorWithProviders extends ColorAndFontCollector{

		IColorProvider colorProvider;

		IFontProvider fontProvider;

		/**
		 * Create a new instance of the receiver using the supplied
		 * label provider. If it is an IColorProvider or IFontProvider
		 * set these values up.
		 * @param provider IBaseLabelProvider
		 * @see IColorProvider
		 * @see IFontProvider
		 */
		public ColorAndFontCollectorWithProviders(IBaseLabelProvider provider) {
			super();
			if (provider instanceof IColorProvider) {
				colorProvider = (IColorProvider) provider;
			}
			if (provider instanceof IFontProvider) {
				fontProvider = (IFontProvider) provider;
			}
		}

		@Override
		public void setFontsAndColors(Object element){

			if(fontProvider != null){
				if(font == null) {
					font = fontProvider.getFont(element);
				}
			}

			if(colorProvider == null) {
				return;
			}
			//Set the colors if they are not set yet
			if(background == null) {
				background = colorProvider.getBackground(element);
			}

			if(foreground == null) {
				foreground = colorProvider.getForeground(element);
			}
		}

		@Override
		public void applyFontsAndColors(TableItem control) {

			if(colorProvider == null){
				if(usedDecorators){
					//If there is no provider only apply set values
					if(background != null) {
						control.setBackground(background);
					}

					if(foreground != null) {
						control.setForeground(foreground);
					}
				}
			}
			else{
				//Always set the value if there is a provider
				control.setBackground(background);
				control.setForeground(foreground);
			}

			if(fontProvider == null){
				if(usedDecorators && font != null) {
					control.setFont(font);
				}
			} else {
				control.setFont(font);
			}

			clear();
		}

		@Override
		public void applyFontsAndColors(TreeItem control) {

			if(colorProvider == null){
				if(usedDecorators){
					//If there is no provider only apply set values
					if(background != null) {
						control.setBackground(background);
					}

					if(foreground != null) {
						control.setForeground(foreground);
					}
				}
			}
			else{
				//Always set the value if there is a provider
				control.setBackground(background);
				control.setForeground(foreground);
			}

			if(fontProvider == null){
				if(usedDecorators && font != null) {
					control.setFont(font);
				}
			} else {
				control.setFont(font);
			}

			clear();
		}

	}

	/**
	 * The ColorAndFontCollector collects fonts and colors without a
	 * a color or font provider.
	 */
	protected class ColorAndFontCollector {

		Color foreground = null;

		Color background = null;

		Font font = null;

		boolean usedDecorators = false;

		/**
		 * Create a new instance of the receiver with
		 * no color and font provider.
		 */
		public ColorAndFontCollector(){
			super();
		}


		/**
		 * Clear all of the results.
		 */
		public void clear() {
			foreground = null;
			background = null;
			font = null;
			usedDecorators = false;
		}


		/**
		 * Set the initial fonts and colors for the element from the
		 * content providers.
		 * @param element Object
		 */
		public void setFontsAndColors(Object element){
			//Do nothing if there are no providers
		}

		/**
		 * Set that decorators were applied.
		 */
		public void setUsedDecorators() {
			this.usedDecorators = true;
		}

		/**
		 * Apply the fonts and colors to the control if required.
		 *
		 * @param control control to apply font and color on
		 */
		public void applyFontsAndColors(TableItem control) {

			if(usedDecorators){
				//If there is no provider only apply set values
				if(background != null) {
					control.setBackground(background);
				}

				if(foreground != null) {
					control.setForeground(foreground);
				}

				if(font != null) {
					control.setFont(font);
				}
			}
			clear();
		}

		/**
		 * Apply the fonts and colors to the control if required.
		 *
		 * @param control control to apply font and color on
		 */
		public void applyFontsAndColors(TreeItem control) {
			if(usedDecorators){
				//If there is no provider only apply set values
				if(background != null) {
					control.setBackground(background);
				}

				if(foreground != null) {
					control.setForeground(foreground);
				}

				if(font != null) {
					control.setFont(font);
				}
			}
			clear();
		}

		/**
		 * Set the background color.
		 *
		 * @param background color to set
		 */
		public void setBackground(Color background) {
			this.background = background;
		}

		/**
		 * Set the font.
		 *
		 * @param font font to set
		 */
		public void setFont(Font font) {
			this.font = font;
		}

		/**
		 * Set the foreground color.
		 *
		 * @param foreground color to set
		 */
		public void setForeground(Color foreground) {
			this.foreground = foreground;
		}


	}

	/**
	 * The safe runnable used to update an item.
	 */
	class UpdateItemSafeRunnable extends SafeRunnable {
		private Widget widget;

		private Object element;

		private boolean fullMap;

		UpdateItemSafeRunnable(Widget widget, Object element, boolean fullMap) {
			this.widget = widget;
			this.element = element;
			this.fullMap = fullMap;
		}

		@Override
		public void run() {
			doUpdateItem(widget, element, fullMap);
		}
	}

	/**
	 * Creates a structured element viewer. The viewer has no input, no content
	 * provider, a default label provider, no sorter, and no filters.
	 */
	protected StructuredViewer() {
		// do nothing
	}

	/**
	 * Adds a listener for double-clicks in this viewer. Has no effect if an
	 * identical listener is already registered.
	 *
	 * @param listener
	 *            a double-click listener
	 */
	public void addDoubleClickListener(IDoubleClickListener listener) {
		doubleClickListeners.add(listener);
	}

	/**
	 * Adds a listener for selection-open in this viewer. Has no effect if an
	 * identical listener is already registered.
	 *
	 * @param listener
	 *            an open listener
	 */
	public void addOpenListener(IOpenListener listener) {
		openListeners.add(listener);
	}

	@Override
	public void addPostSelectionChangedListener(ISelectionChangedListener listener) {
		postSelectionChangedListeners.add(listener);
	}

	/**
	 * Adds support for dragging items out of this viewer via a user
	 * drag-and-drop operation.
	 *
	 * @param operations
	 *            a bitwise OR of the supported drag and drop operation types (
	 *            DROP_COPY,DROP_LINK, and
	 *            DROP_MOVE)
	 * @param transferTypes
	 *            the transfer types that are supported by the drag operation
	 * @param listener
	 *            the callback that will be invoked to set the drag data and to
	 *            cleanup after the drag and drop operation finishes
	 * @see org.eclipse.swt.dnd.DND
	 */
	public void addDragSupport(int operations, Transfer[] transferTypes, DragSourceListener listener) {

		Control myControl = getControl();
		final DragSource dragSource = new DragSource(myControl, operations);
		dragSource.setTransfer(transferTypes);
		dragSource.addDragListener(listener);
	}

	/**
	 * Adds support for dropping items into this viewer via a user drag-and-drop
	 * operation.
	 *
	 * @param operations
	 *            a bitwise OR of the supported drag and drop operation types (
	 *            DROP_COPY,DROP_LINK, and
	 *            DROP_MOVE)
	 * @param transferTypes
	 *            the transfer types that are supported by the drop operation
	 * @param listener
	 *            the callback that will be invoked after the drag and drop
	 *            operation finishes
	 * @see org.eclipse.swt.dnd.DND
	 */
	public void addDropSupport(int operations, Transfer[] transferTypes,
			final DropTargetListener listener) {
		Control control = getControl();
		DropTarget dropTarget = new DropTarget(control, operations);
		dropTarget.setTransfer(transferTypes);
		dropTarget.addDropListener(listener);
	}

	/**
	 * Adds the given filter to this viewer, and triggers refiltering and
	 * resorting of the elements. If you want to add more than one filter
	 * consider using {@link StructuredViewer#setFilters(ViewerFilter...)}.
	 *
	 * @param filter
	 *            a viewer filter
	 * @see StructuredViewer#setFilters(ViewerFilter...)
	 */
	public void addFilter(ViewerFilter filter) {
		if (filters == null) {
			filters = new ArrayList<>();
		}
		filters.add(filter);
		refresh();
	}

	/**
	 * Asserts that the given array of elements is itself non- null
	 * and contains no null elements.
	 *
	 * @param elements
	 *            the array to check
	 */
	protected void assertElementsNotNull(Object... elements) {
		Assert.isNotNull(elements);
		for (Object element : elements) {
			Assert.isNotNull(element);
		}

		if (InternalPolicy.DEBUG_LOG_EQUAL_VIEWER_ELEMENTS
				&& elements.length > 1) {
			CustomHashtable elementSet = newHashtable(elements.length * 2);
			for (Object element : elements) {
				Object old = elementSet.put(element, element);
				if (old != null) {
					String message = "Sibling elements in viewer must not be equal:\n  " //$NON-NLS-1$
							+ old + ",\n  " + element; //$NON-NLS-1$
					Policy.getLog().log(
							new Status(IStatus.WARNING, Policy.JFACE, message,
									new RuntimeException()));
					return;
				}
			}
		}
	}

	/**
	 * Associates the given element with the given widget. Sets the given item's
	 * data to be the element, and maps the element to the item in the element
	 * map (if enabled).
	 *
	 * @param element
	 *            the element
	 * @param item
	 *            the widget
	 */
	protected void associate(Object element, Item item) {
		Object data = item.getData();
		if (data != element) {
			if (data != null) {
				disassociate(item);
			}
			item.setData(element);
			mapElement(element, item);
		} else {
			// Always map the element, even if data == element,
			// since unmapAllElements() can leave the map inconsistent
			// See bug 2741 for details.
			mapElement(element, item);
		}
		if (associateListener != null)
			associateListener.associate(element, item);
	}


	/**
	 * Disassociates the given SWT item from its corresponding element. Sets the
	 * item's data to null and removes the element from the
	 * element map (if enabled).
	 *
	 * @param item
	 *            the widget
	 */
	protected void disassociate(Item item) {
		if (associateListener != null)
			associateListener.disassociate(item);
		Object element = item.getData();
		Assert.isNotNull(element);
		//Clear the map before we clear the data
		unmapElement(element, item);
		item.setData(null);
	}

	/**
	 * Returns the widget in this viewer's control which represents the given
	 * element if it is the viewer's input.
	 * 
	 * This method is internal to the framework; subclassers should not call this
	 * method.
	 * 
	 *
	 * @param element the element to find the representing widget for
	 * @return the corresponding widget, or null if none
	 */
	protected abstract Widget doFindInputItem(Object element);

	/**
	 * Returns the widget in this viewer's control which represent the given
	 * element. This method searches all the children of the input element.
	 * 
	 * This method is internal to the framework; subclassers should not call this
	 * method.
	 * 
	 *
	 * @param element the element to find the representing widget for
	 * @return the corresponding widget, or null if none
	 */
	protected abstract Widget doFindItem(Object element);

	/**
	 * Copies the attributes of the given element into the given SWT item. The
	 * element map is updated according to the value of fullMap.
	 * If fullMap is true then the current mapping
	 * from element to widgets is removed and the new mapping is added. If
	 * full map is false then only the new map gets installed.
	 * Installing only the new map is necessary in cases where only the order of
	 * elements changes but not the set of elements.
	 * 
	 * This method is internal to the framework; subclassers should not call
	 * this method.
	 * 
	 *
	 * @param item widget item to update
	 * @param element the element to represent
	 * @param fullMap
	 *            true if mappings are added and removed, and
	 *            false if only the new map gets installed
	 */
	protected abstract void doUpdateItem(Widget item, Object element, boolean fullMap);

	/**
	 * Compares two elements for equality. Uses the element comparer if one has
	 * been set, otherwise uses the default equals method on the
	 * elements themselves.
	 *
	 * @param elementA
	 *            the first element
	 * @param elementB
	 *            the second element
	 * @return whether elementA is equal to elementB
	 */
	protected boolean equals(Object elementA, Object elementB) {
		if (comparer == null) {
			return elementA == null ? elementB == null : elementA.equals(elementB);
		}
		return elementA == null ? elementB == null : comparer.equals(elementA, elementB);
	}

	/**
	 * Returns the result of running the given elements through the filters.
	 *
	 * @param elements
	 *            the elements to filter
	 * @return only the elements which all filters accept
	 */
	protected Object[] filter(Object[] elements) {
		if (filters != null) {
			List