bundles/org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/internal/dialogs/TreeManager.java

/*******************************************************************************
 * Copyright (c) 2009 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.ui.internal.dialogs;

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

import org.eclipse.swt.graphics.Image;

import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.jface.resource.JFaceResources;
import org.eclipse.jface.resource.LocalResourceManager;
import org.eclipse.jface.viewers.CheckStateChangedEvent;
import org.eclipse.jface.viewers.CheckboxTableViewer;
import org.eclipse.jface.viewers.CheckboxTreeViewer;
import org.eclipse.jface.viewers.IBaseLabelProvider;
import org.eclipse.jface.viewers.ICheckStateListener;
import org.eclipse.jface.viewers.ICheckStateProvider;
import org.eclipse.jface.viewers.ICheckable;
import org.eclipse.jface.viewers.IContentProvider;
import org.eclipse.jface.viewers.ITreeContentProvider;
import org.eclipse.jface.viewers.LabelProvider;
import org.eclipse.jface.viewers.Viewer;

/**
 * Manages a tree which provides "standard checkbox tree behavior". I.e. it
 * follows these rules:
 * <ol>
 * 	<li>If a check box is checked, all its children must be checked.</li>
 * 	<li>If a check box is unchecked, all its children must be unchecked.</li>
 * 	<li>If a check box is grayed, each of its children may be either checked or
 * 		unchecked, however, there must be one of each.</li>
 * 	<li>If a user checks a check box, its children or parents must change state
 * 		accordingly.</li>
 * </ol>
 * <p>
 * <b>Note:</b> be sure to call dispose()
 * </p>
 * @since 3.5
 *
 */
public class TreeManager {
	static final int CHECKSTATE_UNCHECKED = 0;
	static final int CHECKSTATE_GRAY = 1;
	static final int CHECKSTATE_CHECKED = 2;
	
	private static ICheckStateProvider checkStateProvider = null;
	private static IBaseLabelProvider labelProvider = null;
	private static ICheckStateListener viewerCheckListener = null;
	private static ITreeContentProvider treeContentProvider = null;
	
	private List listeners = new ArrayList();
	private LocalResourceManager resourceManager = new LocalResourceManager(JFaceResources.getResources());

	/**
	 * Instances of this interface will handle changes in the model
	 * representation of checkstates.
	 */
	public interface CheckListener {
		/**
		 * Invoked when a {@link TreeManager.TreeItem}'s check state has changed.
		 * 
		 * @param changedItem The item whose check state has changed
		 */
		public void checkChanged(TreeItem changedItem);
	}

	/**
	 * Implementation of {@link TreeManager.CheckListener} for use in a {@link CheckboxTreeViewer}.
	 */
	public static class ModelListenerForCheckboxTree implements CheckListener {
		private CheckboxTreeViewer treeViewer;
		public ModelListenerForCheckboxTree(TreeManager manager, CheckboxTreeViewer treeViewer) {
			this.treeViewer = treeViewer;
			manager.addListener(this);
		}
		
		public void checkChanged(TreeItem changedItem) {
			treeViewer.update(changedItem, null);
		}
	}

	/**
	 * Implementation of {@link TreeManager}CheckListener for use in a
	 * {@link CheckboxTableViewer}.
	 */
	public static class ModelListenerForCheckboxTable implements CheckListener {
		private CheckboxTableViewer tableViewer;
		public ModelListenerForCheckboxTable(TreeManager manager, CheckboxTableViewer tableViewer) {
			this.tableViewer = tableViewer;
			manager.addListener(this);
		}
		
		public void checkChanged(TreeItem changedItem) {
			tableViewer.update(changedItem, null);
		}
	}

	public static class ViewerCheckStateListener implements ICheckStateListener {
		public void checkStateChanged(CheckStateChangedEvent event) {
			Object checked = event.getElement();
			if(checked instanceof TreeItem) {
				((TreeItem)checked).setChangedByUser(true);
				((TreeItem)checked).setCheckState(event.getChecked());
			}
		}
	}

	/**
	 * An {@link ICheckStateProvider} which properly provides checkbox state on
	 * {@link TreeManager.TreeItem}s.
	 */
	public static class CheckStateProvider implements ICheckStateProvider {
		public boolean isChecked(Object element) {
			return ((TreeItem)element).checkState != CHECKSTATE_UNCHECKED;
		}
		
		public boolean isGrayed(Object element) {
			return ((TreeItem)element).checkState == CHECKSTATE_GRAY;
		}
	}

	/**
	 * A {@link IBaseLabelProvider} for {@link TreeManager.TreeItem}s.
	 */
	public static class TreeItemLabelProvider extends LabelProvider {
		public String getText(Object element) {
			return ((TreeItem)element).getLabel();
		}

		public Image getImage(Object element) {
			return ((TreeItem)element).getImage();
		}
	}

	/**
	 * An {@link ITreeContentProvider} for {@link TreeManager.TreeItem}s - will completely build the
	 * tree structure represented by {@link TreeManager.TreeItem}s.
	 */
	public static class TreeItemContentProvider implements ITreeContentProvider {
		public Object[] getChildren(Object parentElement) {
			return ((TreeItem)parentElement).getChildren().toArray();
		}

		public Object getParent(Object element) {
			return ((TreeItem)element).getParent();
		}

		public boolean hasChildren(Object element) {
			return getChildren(element).length > 0;
		}

		public Object[] getElements(Object inputElement) {
			return getChildren(inputElement);
		}

		public void dispose() {}

		public void inputChanged(Viewer viewer, Object oldInput, Object newInput) {}
	}

	/**
	 * @return	an {@link ICheckStateProvider} which will operate on
	 * 		{@link TreeItem}s
	 */
	public static ICheckStateProvider getCheckStateProvider() {
		if(checkStateProvider == null) {
			checkStateProvider = new CheckStateProvider();
		}
		return checkStateProvider;
	}
	
	/**
	 * @return	an {@link IBaseLabelProvider} which will provide the labels and
	 * 		images of {@link TreeItem}s
	 */
	public static IBaseLabelProvider getLabelProvider() {
		if(labelProvider == null) {
			labelProvider = new TreeItemLabelProvider();
		}
		return labelProvider;
	}
	
	/**
	 * @return	an {@link ITreeContentProvider} which will provide
	 * 		{@link TreeItem} content in tree format.
	 */
	public static ITreeContentProvider getTreeContentProvider() {
		if(treeContentProvider == null)
			treeContentProvider = new TreeItemContentProvider();
		return treeContentProvider;
	}
	
	/**
	 * @return	an {@link ICheckStateListener} which will respond to
	 * 		{@link CheckStateChangedEvent}s by updating the model to reflect
	 * 		them
	 */
	public ICheckStateListener getViewerCheckStateListener() {
		if(viewerCheckListener == null)
			viewerCheckListener = new ViewerCheckStateListener();
		return viewerCheckListener;
	}

	/**
	 * A single item in a tree of managed checkbox states.
	 */
	public class TreeItem {
		private String label;
		private ImageDescriptor imageDescriptor;
		private Image image;
		private TreeItem parent;
		private List children;
		private int checkState;
		
		private boolean changedByUser = false;
		
		public TreeItem(String label) {
			this.label = label;
			this.children = new ArrayList();
		}
		
		public String getLabel() {
			return label;
		}

		public void setLabel(String label) {
			this.label = label;
		}

		public Image getImage() {
			if(image == null) {
				if(imageDescriptor == null) {
					return null;
				}
				image = resourceManager.createImage(imageDescriptor);
			}
			return image;
		}

		public void setImageDescriptor(ImageDescriptor imageDescriptor) {
			this.imageDescriptor = imageDescriptor;
		}
		
		public void addChild(TreeItem newChild) {
            newChild.parent = this;
            children.add(newChild);
            synchParents(newChild);
        }
		
		public List getChildren() {
			return children;
		}
		
		public TreeItem getParent() {
			return parent;
		}

        /**
         * An internal call that forwards the change events but does <b>not</b>
         * cause any iterative synchronization to take place.
         * 
         * @param newState
         */
        private void internalSetCheckState(int newState) {
			if (newState == checkState)
				return;
			
			checkState = newState;
			fireListeners(this);
        }

		/**
		 * External call to explicitly set the particular state of a {@link TreeManager.TreeItem}.
		 * This is usually a response to an SWT check changed event generated by a Tree/Table.
		 * 
		 * @param checked
		 */
		public void setCheckState(boolean checked) {
			int newState = checked ? CHECKSTATE_CHECKED : CHECKSTATE_UNCHECKED;
			if (checkState == newState)
				return;
			// Actually set the state and fire the CheckChangeEvent
			internalSetCheckState(newState);
			
			// Enforce the SWT rules for checked/gray behavior
			synchChildren(this);
			synchParents(this);
		}

		/**
		 * From the client's perspective the state is a boolean.
		 * 
		 * @return <code>true</code> if the state is not UNCHECKED
		 */
		public boolean getState() {
			return !(checkState == CHECKSTATE_UNCHECKED);
		}
		
		int getCheckState() {
			return checkState;
		}
		
		/**
		 * If the new state is not "GRAY" then force all children to match that
		 * state (recursively).
		 * 
		 * @param changedItem
		 */
		private void synchChildren(TreeItem changedItem) {
			int newState = changedItem.checkState;
			
			// if the new state is 'GRAY'
			if (newState != CHECKSTATE_GRAY) {
				for (Iterator iterator = changedItem.children.iterator(); iterator
						.hasNext();) {
					TreeItem curItem = (TreeItem) iterator.next();
					curItem.internalSetCheckState(newState);
					curItem.setChangedByUser(changedItem.isChangedByUser());
					
					synchChildren(curItem);
				}
			}
		}
		
		/**
		 * Set the parent's state based on the aggregate state of its children
		 * using the following rules:
		 * <ul>
		 * 	<li>All children checked...parent checked</li>
		 * 	<li>All children unchecked...parent unchecked</li>
		 * 	<li>else...parent GRAY</li>
		 * </ul>
		 * 
		 * @param changedItem
		 */
		private void synchParents(TreeItem changedItem) {
			if(changedItem.parent == null)
				return;
			
			int newState = changedItem.checkState;
			
			if (newState == CHECKSTATE_GRAY) {
				// if the new state is 'GRAY' then -ALL- the parents are gray
				while (changedItem.parent != null && changedItem.parent.checkState != CHECKSTATE_GRAY) {
					changedItem.parent.internalSetCheckState(CHECKSTATE_GRAY);
					changedItem = changedItem.parent;
				}
			} else {
				// compute the parent's state - checked if all children are
				// checked, unchecked if all children are unchecked, gray if
				// some of each
				boolean checkedFound = newState == CHECKSTATE_CHECKED;
				boolean uncheckedFound = newState == CHECKSTATE_UNCHECKED;
				for (Iterator i = changedItem.parent.children.iterator(); i.hasNext() && (!checkedFound || !uncheckedFound);) {
					TreeItem item = (TreeItem) i.next();
					switch(item.checkState) {
					case CHECKSTATE_CHECKED: {
						checkedFound = true;
						break;
					} case CHECKSTATE_GRAY: {
						checkedFound = uncheckedFound = true;
						break;
					} case CHECKSTATE_UNCHECKED: {
						uncheckedFound = true;
						break;
					}}
				}
				
				int oldState = changedItem.parent.checkState;
				if(checkedFound && uncheckedFound) {
					changedItem.parent.internalSetCheckState(CHECKSTATE_GRAY);
				} else if (checkedFound) {
					changedItem.parent.internalSetCheckState(CHECKSTATE_CHECKED);
				} else {
					changedItem.parent.internalSetCheckState(CHECKSTATE_UNCHECKED);
				}
				if(oldState != changedItem.parent.checkState) {
					synchParents(changedItem.parent);
				}
			}
		}

		/**
		 * @param changedByUser The changedByUser to set.
		 */
		public void setChangedByUser(boolean changedByUser) {
			this.changedByUser = changedByUser;
		}

		/**
		 * @return Returns the changedByUser.
		 */
		public boolean isChangedByUser() {
			return changedByUser;
		}
	}
	
	/**
	 * Creates a new {@link TreeManager}.
	 */
	public TreeManager() {
		listeners = new ArrayList();
	}

	/**
	 * Add a {@link CheckListener} whose {@link CheckListener#checkChanged(TreeManager.TreeItem)}
	 * method will be invoked when a {@link TreeItem} created in this {@link TreeManager} has a
	 * check state change.
	 * 
	 * @param listener
	 */
	public void addListener(CheckListener listener) {
		listeners.add(listener);
	}
	
	/**
	 * Provides a {@link CheckListener} which updates a viewer whenever the
	 * {@link TreeManager} model changes.
	 * @param viewer	The viewer whose check states will be appropriately
	 * 		updated on a change to the model.
	 * @return	The created {@link CheckListener}.
	 */
	public CheckListener getCheckListener(ICheckable viewer) {
		if(viewer instanceof CheckboxTreeViewer)
			return new ModelListenerForCheckboxTree(this, (CheckboxTreeViewer)viewer);
		if(viewer instanceof CheckboxTableViewer)
			return new ModelListenerForCheckboxTable(this, (CheckboxTableViewer)viewer);
		return null;
	}
	
	/**
	 * Sets up this {@link TreeManager} for standard interaction with the
	 * provided {@link CheckboxTreeViewer}. In particular:
	 * <ul>
	 * 	<li>Adds a Label Provider for {@link TreeItem}s which provides both
	 * 		labels and images.</li>
	 * 	<li>Adds a {@link CheckStateProvider} for {@link TreeItem}s.</li>
	 * 	<li>Adds an {@link IContentProvider} to build a tree from input
	 * 		{@link TreeItem}s.</li>
	 * 	<li>Adds an {@link ICheckStateListener} to the viewer to update the
	 * 		appropriate {@link TreeItem}s upon a check box state change in the
	 * 		viewer.</li>
	 * 	<li>Adds a {@link CheckListener} to the {@link TreeManager} which will
	 * 		automatically update the viewer on a {@link TreeItem} check state
	 * 		change.</li>
	 * </ul>
	 * @param viewer	the viewer to configure with this TreeManager.
	 */
	public void attachAll(CheckboxTreeViewer viewer) {
		viewer.setLabelProvider(getLabelProvider());
		viewer.setCheckStateProvider(getCheckStateProvider());
		viewer.setContentProvider(getTreeContentProvider());
		viewer.addCheckStateListener(getViewerCheckStateListener());
		getCheckListener(viewer);
	}
	
	/**
	 * Sets up this {@link TreeManager} for standard interaction with the
	 * provided {@link CheckboxTableViewer}. In particular:
	 * <ul>
	 * 	<li>Adds a Label Provider for {@link TreeItem}s which provides both
	 * 		labels and images.</li>
	 * 	<li>Adds a {@link CheckStateProvider} for {@link TreeItem}s.</li>
	 * 	<li>Adds an {@link IContentProvider} to build a tree from input
	 * 		{@link TreeItem}s.</li>
	 * 	<li>Adds an {@link ICheckStateListener} to the viewer to update the
	 * 		appropriate {@link TreeItem}s upon a check box state change in the
	 * 		viewer.</li>
	 * 	<li>Adds a {@link CheckListener} to the {@link TreeManager} which will
	 * 		automatically update the viewer on a {@link TreeItem} check state
	 * 		change.</li>
	 * </ul>
	 * @param viewer	the viewer to configure with this TreeManager.
	 */
	public void attachAll(CheckboxTableViewer viewer) {
		viewer.setLabelProvider(getLabelProvider());
		viewer.setCheckStateProvider(getCheckStateProvider());
		viewer.setContentProvider(getTreeContentProvider());
		viewer.addCheckStateListener(getViewerCheckStateListener());
		getCheckListener(viewer);
	}

	/**
	 * Dissociates a listener.
	 * @param listener	The listener to remove.
	 */
	public void removeListener(CheckListener listener) {
		listeners.remove(listener);
	}
	
	/**
	 * Fires all listeners.
	 * @param item	The {@link TreeItem} that changed.
	 */
	private void fireListeners(TreeItem item) {
		for (Iterator i = listeners.iterator(); i.hasNext();) {
			CheckListener listener = (CheckListener) i.next();
			listener.checkChanged(item);
		}
	}
	
	public void dispose() {
		resourceManager.dispose();
		resourceManager = null;
		listeners.clear();
		listeners = null;
	}
}