org.eclipse.gmf.runtime.common.ui/src/org/eclipse/gmf/runtime/common/ui/dialogs/SelectableElement.java - gmf-runtime/org.eclipse.gmf-runtime - Git at Google

 /******************************************************************************
  * Copyright (c) 2002, 2005 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.gmf.runtime.common.ui.dialogs;

 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Set;
 import java.util.Vector;

 import org.eclipse.jface.resource.ImageDescriptor;
 import org.eclipse.swt.graphics.GC;
 import org.eclipse.swt.graphics.Point;
 import org.eclipse.swt.widgets.Control;

 /**
  * An element that contains a hint, a serializable String ID, a String label,
  * and an ImageDescriptor label.  SeletableElements keep track of its parent
  * which may or may not be null and a list of children which may be empty.
  * This allows SelectableElement objects to be optionally represented in tree
  * viewers.  SelectableElements also keep track of their SelectedType, which
  * describes if the element is selected, unselected, or set to leave.
  * Therefore, SelectableElement objects typically correspond to elements in the
  * UI.
  *
  * <P>This class contains public convenience methods.  For eaxmple, it
  * includes methods to find SelectableElement objects or their hints based on
  * their String ID and a method to make copies of SelectableElement objects.
  *
  * <P>The SelectableElement class is used in at least 3 places, Show Related
  * Elements Show Hide Relationships, and Browse Diagrams.
  *
  * @author Wayne Diu, wdiu
  */
 public class SelectableElement {

 	/**
 	 * Unique identifier for this selectable element.
 	 */
 	private String id;

 	/**
 	 * String name of the element
 	 */
 	private String name;

 	/**
 	 * Icon for the element
 	 */

 	private ImageDescriptor icon;

 	/**
 	 * This element's children
 	 */
 	private Vector children;

 	/**
 	 * True if element was checked by the user, false if it wasn't
 	 */
 	private SelectedType selectedType;

 	/**
 	 * This element's parent
 	 */
 	private SelectableElement parent;

 	/**
 	 * Hint for checking what the type of this element is
 	 */
 	private Object hint;

 	/**
 	 * Adds a child to this element
 	 *
 	 * @param element
 	 *            the child to add
 	 */
 	public void addChild(SelectableElement element) {
 		children.add(element);
 		element.setParent(this);
 	}

 	/**
 	 * Remove all children of this SelectableElement
 	 */
 	public void removeAllChildren() {
 		Iterator i = children.iterator();
 		while (i.hasNext()) {
 			((SelectableElement) i.next()).setParent(null);
 		}
 		children = new Vector();
 	}

 	/**
 	 * Constructor to make a new SelectableElement
 	 *
 	 * @param aName
 	 *            the String name of the element
 	 * @param anIcon
 	 *            the icon Image for the element
 	 * @param aHint
 	 *            the element type
 	 * @deprecated Use the other constructor.
 	 */
 	public SelectableElement(String aName, ImageDescriptor anIcon, Object aHint) {
 		// For now, we will use the name as a unique identifier.
 		this(aName, aName, anIcon, aHint);
 	}

 	/**
 	 * Constructor to make a new SelectableElement.
 	 *
 	 * @param anID
 	 *            A non-language specific unique identifier for this selectable
 	 *            element.
 	 * @param aName
 	 *            A user-presentable name for this selectable element.
 	 * @param anIcon
 	 *            The icon image for the element.
 	 * @param aHint
 	 *            A hint associated with the selection of this element.
 	 */
 	public SelectableElement(String anID, String aName, ImageDescriptor anIcon,
 			Object aHint) {
 		children = new Vector();
 		this.id = anID;
 		this.name = aName;
 		this.icon = anIcon;
 		this.hint = aHint;
 		selectedType = SelectedType.UNSELECTED;
 	}

 	/**
 	 * Returns the number of children
 	 *
 	 * @return int with the number of children this element has
 	 */
 	public int getNumberOfChildren() {
 		return children.size();
 	}

 	/**
 	 * Returns a child
 	 *
 	 * @param i
 	 *            with the index of the child of this element
 	 * @return SelectableElement which is child i of this element
 	 */
 	public SelectableElement getChild(int i) {
 		assert (i >= 0 && i < children.size());
 		return (SelectableElement) children.get(i);
 	}

 	/**
 	 * Returns the icon of this element to display to the user.
 	 *
 	 * @return Image with icon of this element to display to the user
 	 */
 	public ImageDescriptor getIconImageDescriptor() {
 		return icon;
 	}

 	/**
 	 * Returns the name of this element to display to the user.
 	 *
 	 * @return String with name of this element to display to the user
 	 */
 	public String getName() {
 		return name;
 	}

 	/**
 	 * Sets the icon of this element to display to the user.
 	 *
 	 * @param anIcon
 	 *            The icon to set
 	 */
 	public void setIconImageDescriptor(ImageDescriptor anIcon) {
 		this.icon = anIcon;
 	}

 	/**
 	 * Sets the name of this element to display to the user.
 	 *
 	 * @param aName
 	 *            The name to set
 	 */
 	public void setName(String aName) {
 		this.name = aName;
 	}

 	/**
 	 * Returns the parent of this element.
 	 *
 	 * @return SelectableElement
 	 */
 	public SelectableElement getParent() {
 		return parent;
 	}

 	/**
 	 * Sets the parent of this element.
 	 *
 	 * @param aParent
 	 *            The parent to set
 	 */
 	public void setParent(SelectableElement aParent) {
 		this.parent = aParent;
 	}

 	/**
 	 * Returns the children of this element as an array
 	 *
 	 * @return SelectableElement[] array of this element's children.
 	 */
 	public SelectableElement[] getChildren() {
 		SelectableElement elements[] = new SelectableElement[getNumberOfChildren()];
 		for (int i = 0; i < getNumberOfChildren(); i++) {
 			elements[i] = (SelectableElement) children.elementAt(i);
 		}
 		return elements;
 	}

 	/**
 	 * Returns if the element was selected.
 	 *
 	 * @return selectedType from the SelectedType EnumeratedType
 	 */
 	public SelectedType getSelectedType() {
 		return selectedType;
 	}

 	/**
 	 * Sets whether or not the element is selected. For example, if the element
 	 * is checked in the interface.
 	 *
 	 * @param aSelectedType
 	 *            from the SelectedType EnumeratedType
 	 */
 	public void setSelectedType(SelectedType aSelectedType) {
 		this.selectedType = aSelectedType;
 	}

 	/**
 	 * Returns the hint, which is an Object. This could be subclassed if type
 	 * safety is required.
 	 *
 	 * @return the element type
 	 */
 	public Object getHint() {
 		return hint;
 	}

 	/**
 	 * Sets the SelectedType for a SelectableElement and its children
 	 *
 	 * @param parent
 	 *            sets the SelectedType for this SelectableElement
 	 * @param selectedType
 	 *            the SelectedType to set for the SelectableElement and its
 	 *            children.
 	 */
 	public static void setSelectedTypeForSelecteableElementAndChildren(
 			SelectableElement parent, SelectedType selectedType) {
 		for (int i = 0; i < parent.getNumberOfChildren(); i++) {
 			setSelectedTypeForSelecteableElementAndChildren(parent.getChild(i),
 				selectedType);
 		}
 		parent.setSelectedType(selectedType);
 	}

 	/**
 	 * Sets the SelectedType for a SelectableElement and its children that match
 	 * the IDs in the List of IDs.
 	 *
 	 * @param parent
 	 *            sets the SelectedType for this SelectableElement
 	 * @param selectedType
 	 *            the SelectedType to set for the SelectableElement and its
 	 *            children.
 	 * @param list
 	 *            List of IDs, not hints
 	 */
 	public static void setSelectedTypeForMatchingSelecteableElementAndChildren(
 			SelectableElement parent, SelectedType selectedType, List list) {
 		for (int i = 0; i < parent.getNumberOfChildren(); i++) {
 			setSelectedTypeForMatchingSelecteableElementAndChildren(parent
 				.getChild(i), selectedType, list);
 		}

 		if (list.contains(parent.getId())) {
 			setSelectedTypeForSelecteableElementAndChildren(parent,
 				selectedType);
 		}

 	}

 	/**
 	 * Calculates the longest string length of this element's children for the
 	 * text that will be displayed in the control. This method only works for
 	 * root SelectableElements.
 	 *
 	 * @param selectableElement
 	 *            the SelectableElement to calculate the longest string length.
 	 *            Also looks at its children.
 	 * @param control
 	 *            the control with the font to use when calculating the font
 	 *            size
 	 * @return int with the string length in pixels
 	 */
 	public static int calculateLongestStringLength(
 			SelectableElement selectableElement, Control control) {
 		int INITIAL_LONGEST_STRING_LENGTH = 0;
 		int INITIAL_ITERATION_LEVEL = -1; //there is a fake element

 		assert (selectableElement.getParent() == null);

 		GC gc = new GC(control);
 		int longestStringLength = calculateLongestStringLength(
 			selectableElement, gc, INITIAL_LONGEST_STRING_LENGTH,
 			INITIAL_ITERATION_LEVEL);
 		gc.dispose();
 		return longestStringLength;
 	}

 	/**
 	 * Calculates the longest string length of this element's children for the
 	 * text that will be displayed.
 	 *
 	 * @param selectableElement
 	 *            the SelectableElement to calculate the longest string length.
 	 *            Also looks at its children.
 	 * @param gc
 	 *            the GC to use when calculating the font size
 	 * @param longestStringLength
 	 *            the longest string length for the selectableElement and its
 	 *            children so far.
 	 * @param iterationLevel
 	 *            how many levels we have gone to keep track of the indents of
 	 *            the icons
 	 * @return int with the string length in pixels
 	 */
 	private static int calculateLongestStringLength(
 			SelectableElement selectableElement, GC gc,
 			int longestStringLength, int iterationLevel) {
 		int ICON_WIDTH = 32;
 		//we don'internationalize these icons, checkbox is 16 and image is 16
 		Point size = gc.textExtent(selectableElement.getName());
 		if (size.x + (iterationLevel * ICON_WIDTH) > longestStringLength)
 			longestStringLength = size.x + (iterationLevel * ICON_WIDTH);
 		for (int i = 0; i < selectableElement.getNumberOfChildren(); i++) {
 			longestStringLength = calculateLongestStringLength(
 				selectableElement.getChild(i), gc, longestStringLength,
 				iterationLevel + 1);
 		}
 		return longestStringLength;
 	}

 	/**
 	 * Returns the number of children including itself. Includes children that
 	 * are children of children, etc.
 	 *
 	 * @param selectableElement
 	 *            the SelectableElement that we will find the number of children
 	 *            for.
 	 * @return int the number of children including children that are children
 	 *         of children, etc, and itself.
 	 */
 	public static int calculateNumberOfChildren(
 			SelectableElement selectableElement) {
 		int numberOfChildren = 0;
 		for (int i = 0; i < selectableElement.getNumberOfChildren(); i++) {
 			numberOfChildren += calculateNumberOfChildren(selectableElement
 				.getChild(i));
 		}
 		return numberOfChildren + 1;
 	}

 	/**
 	 * Recursively checks SelectableElement and its children to determine which
 	 * elements have the specified selectedType. If a SelectableElement meets
 	 * the type criteria, its hint (RelationshipType) is added to the
 	 * matchingElements list.
 	 *
 	 * @param matchingElements
 	 * @param typeToMatch
 	 */
 	private void getMatchingElementTypes(List matchingElements,
 			SelectedType typeToMatch) {

 		for (int i = 0; i < getNumberOfChildren(); i++) {
 			getChild(i).getMatchingElementTypes(matchingElements, typeToMatch);
 		}
 		if (getSelectedType() == typeToMatch && getHint() != null) {
 			if (getHint() instanceof Collection)
 				matchingElements.addAll((Collection) getHint());
 			else
 				matchingElements.add(getHint());
 		}
 	}

 	/**
 	 * Returns a list of SELECTED RelationshipTypes for a SelectableElement.
 	 *
 	 * Checks this SelectableElement and the SelectableElement's children. For
 	 * each SelectableElement where the selectedType is SELECTED, add the
 	 * RelationshipType to a list.
 	 *
 	 * @return List
 	 */
 	public List getSelectedElementTypes() {
 		List selectedElements = new Vector();
 		getMatchingElementTypes(selectedElements, SelectedType.SELECTED);
 		return selectedElements;
 	}

 	/**
 	 * Returns a list of UNSELECTED RelationshipTypes for a SelectableElement.
 	 *
 	 * Checks this SelectableElement and the SelectableElement's children. For
 	 * each SelectableElement where the selectedType is UNSELECTED, add the
 	 * RelationshipType to a list.
 	 *
 	 * @return List
 	 */
 	public List getUnSelectedElementTypes() {
 		List unselectedElements = new Vector();
 		getMatchingElementTypes(unselectedElements, SelectedType.UNSELECTED);
 		return unselectedElements;
 	}

 	/**
 	 * Returns a list of LEAVE RelationshipTypes for a SelectableElement.
 	 *
 	 * Checks this SelectableElement and the SelectableElement's children. For
 	 * each SelectableElement where the selectedType is LEAVE, add the
 	 * RelationshipType to a list.
 	 *
 	 * @return List
 	 */
 	public List getLeaveElementTypes() {
 		List leaveElements = new Vector();
 		getMatchingElementTypes(leaveElements, SelectedType.LEAVE);
 		return leaveElements;
 	}

 	/**
 	 * Returns a string representation of this selectable element. This is
 	 * useful if a selectable element must be persisted between invocations of
 	 * eclipse.
 	 *
 	 * @return String id of this selectableElement
 	 */
 	public String getId() {
 		return id;
 	}

 	/**
 	 * Retrieves all of the hints from the list of selections. The selections
 	 * are strings that have been produced by the getId() method. Note: this
 	 * should be invoked from the selectable element root.
 	 *
 	 * @param stringRepresentations
 	 *            Strings produced by the {@link SelectableElement#getId()}
 	 *            method.
 	 * @param hints
 	 *            (out) A set used to store all of the hints.
 	 */
 	public void getHints(List stringRepresentations, Set hints) {
 		// If we have hit a string representation that is fully selected
 		//  then we simply retrieve all of the hints for this subtree. For
 		//  this selectable element to have been in the "SELECTED" state, it
 		//  and all of its children were selected.
 		if (stringRepresentations.contains(getId())) {
 			getAllHints(hints);
 		} else {
 			for (Iterator i = children.iterator(); i.hasNext();) {
 				((SelectableElement) i.next()).getHints(stringRepresentations,
 					hints);
 			}
 		}
 	}

 	/**
 	 * Retrieve all hints for the subtree rooted at this selectable element.
 	 *
 	 * @param hints
 	 *            (out) A set used to store all of the hints.
 	 */
 	public void getAllHints(Set hints) {
 		if (hint instanceof List)
 			hints.addAll((List) hint);
 		else if (hint != null)
 			hints.add(hint);
 		for (Iterator i = children.iterator(); i.hasNext();) {
 			((SelectableElement) i.next()).getAllHints(hints);
 		}
 	}

 	/**
 	 * Recursively add this SelectableElement's and this SelectableElement's
 	 * children's hints to a List which is not null.
 	 *
 	 * It will not add duplicates into the List, and if the hint is null, it
 	 * will not be added to the List.
 	 *
 	 * @param list
 	 *            not null, add hints to this List
 	 * @param selectableElement
 	 *            recursively add hints from this SelectableElement and its
 	 *            children
 	 */
 	public static void addHintsToList(List list,
 			SelectableElement selectableElement) {
 		assert null != list;
 		assert null != selectableElement;
 		for (int i = 0; i < selectableElement.getNumberOfChildren(); i++) {
 			addHintsToList(list, selectableElement.getChild(i));
 		}

 		Object hint = selectableElement.getHint();
 		if (hint != null) {
 			//I disagree that hint should be sometimes a List, and sometimes an
 			//element, but I will support it
 			if (hint instanceof List) {
 				Iterator it = ((List) hint).iterator();
 				while (it.hasNext()) {
 					Object nestedHint = it.next();
 					if (!list.contains(nestedHint)) {
 						list.add(nestedHint);
 					}
 				}
 			} else if (!list.contains(hint))
 				list.add(hint);
 		}
 	}

 	/**
 	 * Returns if all children have the same selected type
 	 *
 	 * @return true if all children are checked, false otherwise
 	 * @param parent
 	 *            we'll be checking the children of this parent
 	 * @param selectType
 	 *            the SelectedType that all children of the parent are checked
 	 *            for
 	 */
 	public static boolean doAllChildrenHaveSelectedType(
 			SelectableElement parent, SelectedType selectType) {
 		for (int i = 0; i < parent.getNumberOfChildren(); i++) {
 			if (parent.getChild(i).getSelectedType() != selectType)
 				return false;
 		}
 		return true;
 	}

 	/**
 	 * Return all children that have the SelectedType.
 	 *
 	 * @param parent
 	 *            parent selectable element.
 	 * @param selectType
 	 *            the selected type to match
 	 * @param list
 	 *            of SelectableElements
 	 */
 	public static void getAllChildrenOfType(SelectableElement parent,
 			SelectedType selectType, List list) {
 		assert null != list;

 		for (int i = 0; i < parent.getNumberOfChildren(); i++) {
 			if (parent.getChild(i).getSelectedType() == selectType) {
 				list.add(parent.getChild(i));
 			}

 			getAllChildrenOfType(parent.getChild(i), selectType, list);
 		}
 	}

 	/**
 	 * Return element IDs, including children, that are SelectedType.SELECTED.
 	 *
 	 * @return List of element IDs, including children, that are
 	 *         SelectedType.SELECTED.
 	 */
 	public List getSelectedElementIds() {
 		List list = new ArrayList();
 		getMatchingElementIds(list, SelectedType.SELECTED);
 		return list;
 	}

 	/**
 	 * Return matching element IDs that match the typeToMatch.
 	 *
 	 * @param matchingIds
 	 *            List of String ids we are filling
 	 * @param typeToMatch
 	 *            going to match this type
 	 */
 	private void getMatchingElementIds(List matchingIds,
 			SelectedType typeToMatch) {

 		for (int i = 0; i < getNumberOfChildren(); i++) {
 			getChild(i).getMatchingElementIds(matchingIds, typeToMatch);
 		}
 		if (getSelectedType() == typeToMatch) {
 			matchingIds.add(getId());
 		}
 	}

 	/**
 	 * Same idea as the clone method. Share the same images, hints, etc. of the
 	 * original. Just have different SelectableElements.
 	 *
 	 * @return a copy of this selectableElement
 	 */
 	public SelectableElement makeCopy() {
 		SelectableElement selectableElement = immediateCopy(this);
 		copyChildren(this, selectableElement);
 		return selectableElement;
 	}

 	/**
 	 * Used by the copy method. Not suprisingly, this returns a copy of the src
 	 *
 	 * @param src
 	 *            children will be copied from here
 	 * @return SelectableElement which is a copy of the src
 	 */
 	private SelectableElement immediateCopy(SelectableElement src) {
 		SelectableElement selectableElement = new SelectableElement(
 			src.getId(), src.getName(), src.getIconImageDescriptor(), src
 				.getHint());
 		selectableElement.setSelectedType(src.getSelectedType());
 		return selectableElement;
 	}

 	/**
 	 * Used by the copy method. Not surprisingly, this copies the children of
 	 * src into dest.
 	 *
 	 * @param src
 	 *            children will be copied from here
 	 * @param dest
 	 *            children are copied into here
 	 */
 	private void copyChildren(SelectableElement src, SelectableElement dest) {
 		for (int i = 0; i < src.getNumberOfChildren(); i++) {
 			dest.addChild(immediateCopy(src.getChild(i)));
 			copyChildren(src.getChild(i), dest.getChild(i));
 		}
 	}

 	/**
 	 * Collect all the hints of the children into a list.
 	 *
 	 * @param list
 	 *            that I am collecting the hints into.
 	 */
 	private void collectChildrenHints(List list) {
 		Object aHint = getHint();
 		if (aHint instanceof List) {
 			Iterator it = ((List) aHint).iterator();
 			while (it.hasNext()) {
 				Object obj = it.next();
 				if (!list.contains(obj))
 					list.add(obj);
 			}

 		} else if (aHint != null) {
 			if (!list.contains(aHint))
 				list.add(aHint);
 		}

 		for (int i = 0; i < getChildren().length; i++) {
 			getChild(i).collectChildrenHints(list);
 		}
 	}

 	/**
 	 * Collect the types that match a list of String ids. Unlike getHints, which
 	 * doesn't collect children hints.
 	 *
 	 * @param list
 	 *            List to add into
 	 * @param ids
 	 *            List of String ids we are trying to match
 	 */
 	public void getHintsThatMatchTheseIds(List list, List ids) {
 		for (int i = 0; i < getNumberOfChildren(); i++) {
 			if (ids.contains(getChild(i).getId())) {
 				getChild(i).collectChildrenHints(list);
 			} else {
 				getChild(i).getHintsThatMatchTheseIds(list, ids);
 			}
 		}
 	}

 	/**
 	 * Return the first element that matches the given id from the List of
 	 * SelectableElement objects
 	 *
 	 * @param selectableElements
 	 *            List of SelectableElement objects to match
 	 * @param id
 	 *            String id to match
 	 * @return the first element that matches the given id from the List of
 	 *         SelectableElement objects or null if nothing matched
 	 */
 	public static SelectableElement findById(List selectableElements, String id) {
 		assert null != selectableElements;
 		Iterator it = selectableElements.iterator();

 		while (it.hasNext()) {
 			Object obj = it.next();
 			assert (obj instanceof SelectableElement);

 			SelectableElement selectableElement = (SelectableElement) obj;
 			if (id.equals(selectableElement.getId())) {
 				return selectableElement;
 			}
 		}

 		return null;
 	}

 	/**
 	 * Return the first element that matches the given id from this
 	 * SelectableElement and its children
 	 *
 	 * @param theId
 	 *            String id to match
 	 * @return the first element that matches the given id from this
 	 *         SelectableElement and its children or null if nothing matched
 	 */
 	public SelectableElement findById(String theId) {

 		assert null != theId;
 		if (theId.equals(this.getId())) {
 			return this;
 		}

 		for (int i = 0; i < getNumberOfChildren(); i++) {
 			SelectableElement element = getChild(i).findById(theId);
 			if (element != null)
 				return element;
 		}

 		return null;
 	}

 }
	/******************************************************************************
	* Copyright (c) 2002, 2005 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.gmf.runtime.common.ui.dialogs;

	import java.util.ArrayList;
	import java.util.Collection;
	import java.util.Iterator;
	import java.util.List;
	import java.util.Set;
	import java.util.Vector;

	import org.eclipse.jface.resource.ImageDescriptor;
	import org.eclipse.swt.graphics.GC;
	import org.eclipse.swt.graphics.Point;
	import org.eclipse.swt.widgets.Control;

	/**
	* An element that contains a hint, a serializable String ID, a String label,
	* and an ImageDescriptor label. SeletableElements keep track of its parent
	* which may or may not be null and a list of children which may be empty.
	* This allows SelectableElement objects to be optionally represented in tree
	* viewers. SelectableElements also keep track of their SelectedType, which
	* describes if the element is selected, unselected, or set to leave.
	* Therefore, SelectableElement objects typically correspond to elements in the
	* UI.
	*
	* <P>This class contains public convenience methods. For eaxmple, it
	* includes methods to find SelectableElement objects or their hints based on
	* their String ID and a method to make copies of SelectableElement objects.
	*
	* <P>The SelectableElement class is used in at least 3 places, Show Related
	* Elements Show Hide Relationships, and Browse Diagrams.
	*
	* @author Wayne Diu, wdiu
	*/
	public class SelectableElement {

	/**
	* Unique identifier for this selectable element.
	*/
	private String id;

	/**
	* String name of the element
	*/
	private String name;

	/**
	* Icon for the element
	*/

	private ImageDescriptor icon;

	/**
	* This element's children
	*/
	private Vector children;

	/**
	* True if element was checked by the user, false if it wasn't
	*/
	private SelectedType selectedType;

	/**
	* This element's parent
	*/
	private SelectableElement parent;

	/**
	* Hint for checking what the type of this element is
	*/
	private Object hint;

	/**
	* Adds a child to this element
	*
	* @param element
	* the child to add
	*/
	public void addChild(SelectableElement element) {
	children.add(element);
	element.setParent(this);
	}

	/**
	* Remove all children of this SelectableElement
	*/
	public void removeAllChildren() {
	Iterator i = children.iterator();
	while (i.hasNext()) {
	((SelectableElement) i.next()).setParent(null);
	}
	children = new Vector();
	}

	/**
	* Constructor to make a new SelectableElement
	*
	* @param aName
	* the String name of the element
	* @param anIcon
	* the icon Image for the element
	* @param aHint
	* the element type
	* @deprecated Use the other constructor.
	*/
	public SelectableElement(String aName, ImageDescriptor anIcon, Object aHint) {
	// For now, we will use the name as a unique identifier.
	this(aName, aName, anIcon, aHint);
	}

	/**
	* Constructor to make a new SelectableElement.
	*
	* @param anID
	* A non-language specific unique identifier for this selectable
	* element.
	* @param aName
	* A user-presentable name for this selectable element.
	* @param anIcon
	* The icon image for the element.
	* @param aHint
	* A hint associated with the selection of this element.
	*/
	public SelectableElement(String anID, String aName, ImageDescriptor anIcon,
	Object aHint) {
	children = new Vector();
	this.id = anID;
	this.name = aName;
	this.icon = anIcon;
	this.hint = aHint;
	selectedType = SelectedType.UNSELECTED;
	}

	/**
	* Returns the number of children
	*
	* @return int with the number of children this element has
	*/
	public int getNumberOfChildren() {
	return children.size();
	}

	/**
	* Returns a child
	*
	* @param i
	* with the index of the child of this element
	* @return SelectableElement which is child i of this element
	*/
	public SelectableElement getChild(int i) {
	assert (i >= 0 && i < children.size());
	return (SelectableElement) children.get(i);
	}

	/**
	* Returns the icon of this element to display to the user.
	*
	* @return Image with icon of this element to display to the user
	*/
	public ImageDescriptor getIconImageDescriptor() {
	return icon;
	}

	/**
	* Returns the name of this element to display to the user.
	*
	* @return String with name of this element to display to the user
	*/
	public String getName() {
	return name;
	}

	/**
	* Sets the icon of this element to display to the user.
	*
	* @param anIcon
	* The icon to set
	*/
	public void setIconImageDescriptor(ImageDescriptor anIcon) {
	this.icon = anIcon;
	}

	/**
	* Sets the name of this element to display to the user.
	*
	* @param aName
	* The name to set
	*/
	public void setName(String aName) {
	this.name = aName;
	}

	/**
	* Returns the parent of this element.
	*
	* @return SelectableElement
	*/
	public SelectableElement getParent() {
	return parent;
	}

	/**
	* Sets the parent of this element.
	*
	* @param aParent
	* The parent to set
	*/
	public void setParent(SelectableElement aParent) {
	this.parent = aParent;
	}

	/**
	* Returns the children of this element as an array
	*
	* @return SelectableElement[] array of this element's children.
	*/
	public SelectableElement[] getChildren() {
	SelectableElement elements[] = new SelectableElement[getNumberOfChildren()];
	for (int i = 0; i < getNumberOfChildren(); i++) {
	elements[i] = (SelectableElement) children.elementAt(i);
	}
	return elements;
	}

	/**
	* Returns if the element was selected.
	*
	* @return selectedType from the SelectedType EnumeratedType
	*/
	public SelectedType getSelectedType() {
	return selectedType;
	}

	/**
	* Sets whether or not the element is selected. For example, if the element
	* is checked in the interface.
	*
	* @param aSelectedType
	* from the SelectedType EnumeratedType
	*/
	public void setSelectedType(SelectedType aSelectedType) {
	this.selectedType = aSelectedType;
	}

	/**
	* Returns the hint, which is an Object. This could be subclassed if type
	* safety is required.
	*
	* @return the element type
	*/
	public Object getHint() {
	return hint;
	}

	/**
	* Sets the SelectedType for a SelectableElement and its children
	*
	* @param parent
	* sets the SelectedType for this SelectableElement
	* @param selectedType
	* the SelectedType to set for the SelectableElement and its
	* children.
	*/
	public static void setSelectedTypeForSelecteableElementAndChildren(
	SelectableElement parent, SelectedType selectedType) {
	for (int i = 0; i < parent.getNumberOfChildren(); i++) {
	setSelectedTypeForSelecteableElementAndChildren(parent.getChild(i),
	selectedType);
	}
	parent.setSelectedType(selectedType);
	}

	/**
	* Sets the SelectedType for a SelectableElement and its children that match
	* the IDs in the List of IDs.
	*
	* @param parent
	* sets the SelectedType for this SelectableElement
	* @param selectedType
	* the SelectedType to set for the SelectableElement and its
	* children.
	* @param list
	* List of IDs, not hints
	*/
	public static void setSelectedTypeForMatchingSelecteableElementAndChildren(
	SelectableElement parent, SelectedType selectedType, List list) {
	for (int i = 0; i < parent.getNumberOfChildren(); i++) {
	setSelectedTypeForMatchingSelecteableElementAndChildren(parent
	.getChild(i), selectedType, list);
	}

	if (list.contains(parent.getId())) {
	setSelectedTypeForSelecteableElementAndChildren(parent,
	selectedType);
	}

	}

	/**
	* Calculates the longest string length of this element's children for the
	* text that will be displayed in the control. This method only works for
	* root SelectableElements.
	*
	* @param selectableElement
	* the SelectableElement to calculate the longest string length.
	* Also looks at its children.
	* @param control
	* the control with the font to use when calculating the font
	* size
	* @return int with the string length in pixels
	*/
	public static int calculateLongestStringLength(
	SelectableElement selectableElement, Control control) {
	int INITIAL_LONGEST_STRING_LENGTH = 0;
	int INITIAL_ITERATION_LEVEL = -1; //there is a fake element

	assert (selectableElement.getParent() == null);

	GC gc = new GC(control);
	int longestStringLength = calculateLongestStringLength(
	selectableElement, gc, INITIAL_LONGEST_STRING_LENGTH,
	INITIAL_ITERATION_LEVEL);
	gc.dispose();
	return longestStringLength;
	}

	/**
	* Calculates the longest string length of this element's children for the
	* text that will be displayed.
	*
	* @param selectableElement
	* the SelectableElement to calculate the longest string length.
	* Also looks at its children.
	* @param gc
	* the GC to use when calculating the font size
	* @param longestStringLength
	* the longest string length for the selectableElement and its
	* children so far.
	* @param iterationLevel
	* how many levels we have gone to keep track of the indents of
	* the icons
	* @return int with the string length in pixels
	*/
	private static int calculateLongestStringLength(
	SelectableElement selectableElement, GC gc,
	int longestStringLength, int iterationLevel) {
	int ICON_WIDTH = 32;
	//we don'internationalize these icons, checkbox is 16 and image is 16
	Point size = gc.textExtent(selectableElement.getName());
	if (size.x + (iterationLevel * ICON_WIDTH) > longestStringLength)
	longestStringLength = size.x + (iterationLevel * ICON_WIDTH);
	for (int i = 0; i < selectableElement.getNumberOfChildren(); i++) {
	longestStringLength = calculateLongestStringLength(
	selectableElement.getChild(i), gc, longestStringLength,
	iterationLevel + 1);
	}
	return longestStringLength;
	}

	/**
	* Returns the number of children including itself. Includes children that
	* are children of children, etc.
	*
	* @param selectableElement
	* the SelectableElement that we will find the number of children
	* for.
	* @return int the number of children including children that are children
	* of children, etc, and itself.
	*/
	public static int calculateNumberOfChildren(
	SelectableElement selectableElement) {
	int numberOfChildren = 0;
	for (int i = 0; i < selectableElement.getNumberOfChildren(); i++) {
	numberOfChildren += calculateNumberOfChildren(selectableElement
	.getChild(i));
	}
	return numberOfChildren + 1;
	}

	/**
	* Recursively checks SelectableElement and its children to determine which
	* elements have the specified selectedType. If a SelectableElement meets
	* the type criteria, its hint (RelationshipType) is added to the
	* matchingElements list.
	*
	* @param matchingElements
	* @param typeToMatch
	*/
	private void getMatchingElementTypes(List matchingElements,
	SelectedType typeToMatch) {

	for (int i = 0; i < getNumberOfChildren(); i++) {
	getChild(i).getMatchingElementTypes(matchingElements, typeToMatch);
	}
	if (getSelectedType() == typeToMatch && getHint() != null) {
	if (getHint() instanceof Collection)
	matchingElements.addAll((Collection) getHint());
	else
	matchingElements.add(getHint());
	}
	}

	/**
	* Returns a list of SELECTED RelationshipTypes for a SelectableElement.
	*
	* Checks this SelectableElement and the SelectableElement's children. For
	* each SelectableElement where the selectedType is SELECTED, add the
	* RelationshipType to a list.
	*
	* @return List
	*/
	public List getSelectedElementTypes() {
	List selectedElements = new Vector();
	getMatchingElementTypes(selectedElements, SelectedType.SELECTED);
	return selectedElements;
	}

	/**
	* Returns a list of UNSELECTED RelationshipTypes for a SelectableElement.
	*
	* Checks this SelectableElement and the SelectableElement's children. For
	* each SelectableElement where the selectedType is UNSELECTED, add the
	* RelationshipType to a list.
	*
	* @return List
	*/
	public List getUnSelectedElementTypes() {
	List unselectedElements = new Vector();
	getMatchingElementTypes(unselectedElements, SelectedType.UNSELECTED);
	return unselectedElements;
	}

	/**
	* Returns a list of LEAVE RelationshipTypes for a SelectableElement.
	*
	* Checks this SelectableElement and the SelectableElement's children. For
	* each SelectableElement where the selectedType is LEAVE, add the
	* RelationshipType to a list.
	*
	* @return List
	*/
	public List getLeaveElementTypes() {
	List leaveElements = new Vector();
	getMatchingElementTypes(leaveElements, SelectedType.LEAVE);
	return leaveElements;
	}

	/**
	* Returns a string representation of this selectable element. This is
	* useful if a selectable element must be persisted between invocations of
	* eclipse.
	*
	* @return String id of this selectableElement
	*/
	public String getId() {
	return id;
	}

	/**
	* Retrieves all of the hints from the list of selections. The selections
	* are strings that have been produced by the getId() method. Note: this
	* should be invoked from the selectable element root.
	*
	* @param stringRepresentations
	* Strings produced by the {@link SelectableElement#getId()}
	* method.
	* @param hints
	* (out) A set used to store all of the hints.
	*/
	public void getHints(List stringRepresentations, Set hints) {
	// If we have hit a string representation that is fully selected
	// then we simply retrieve all of the hints for this subtree. For
	// this selectable element to have been in the "SELECTED" state, it
	// and all of its children were selected.
	if (stringRepresentations.contains(getId())) {
	getAllHints(hints);
	} else {
	for (Iterator i = children.iterator(); i.hasNext();) {
	((SelectableElement) i.next()).getHints(stringRepresentations,
	hints);
	}
	}
	}

	/**
	* Retrieve all hints for the subtree rooted at this selectable element.
	*
	* @param hints
	* (out) A set used to store all of the hints.
	*/
	public void getAllHints(Set hints) {
	if (hint instanceof List)
	hints.addAll((List) hint);
	else if (hint != null)
	hints.add(hint);
	for (Iterator i = children.iterator(); i.hasNext();) {
	((SelectableElement) i.next()).getAllHints(hints);
	}
	}

	/**
	* Recursively add this SelectableElement's and this SelectableElement's
	* children's hints to a List which is not null.
	*
	* It will not add duplicates into the List, and if the hint is null, it
	* will not be added to the List.
	*
	* @param list
	* not null, add hints to this List
	* @param selectableElement
	* recursively add hints from this SelectableElement and its
	* children
	*/
	public static void addHintsToList(List list,
	SelectableElement selectableElement) {
	assert null != list;
	assert null != selectableElement;
	for (int i = 0; i < selectableElement.getNumberOfChildren(); i++) {
	addHintsToList(list, selectableElement.getChild(i));
	}

	Object hint = selectableElement.getHint();
	if (hint != null) {
	//I disagree that hint should be sometimes a List, and sometimes an
	//element, but I will support it
	if (hint instanceof List) {
	Iterator it = ((List) hint).iterator();
	while (it.hasNext()) {
	Object nestedHint = it.next();
	if (!list.contains(nestedHint)) {
	list.add(nestedHint);
	}
	}
	} else if (!list.contains(hint))
	list.add(hint);
	}
	}

	/**
	* Returns if all children have the same selected type
	*
	* @return true if all children are checked, false otherwise
	* @param parent
	* we'll be checking the children of this parent
	* @param selectType
	* the SelectedType that all children of the parent are checked
	* for
	*/
	public static boolean doAllChildrenHaveSelectedType(
	SelectableElement parent, SelectedType selectType) {
	for (int i = 0; i < parent.getNumberOfChildren(); i++) {
	if (parent.getChild(i).getSelectedType() != selectType)
	return false;
	}
	return true;
	}

	/**
	* Return all children that have the SelectedType.
	*
	* @param parent
	* parent selectable element.
	* @param selectType
	* the selected type to match
	* @param list
	* of SelectableElements
	*/
	public static void getAllChildrenOfType(SelectableElement parent,
	SelectedType selectType, List list) {
	assert null != list;

	for (int i = 0; i < parent.getNumberOfChildren(); i++) {
	if (parent.getChild(i).getSelectedType() == selectType) {
	list.add(parent.getChild(i));
	}

	getAllChildrenOfType(parent.getChild(i), selectType, list);
	}
	}

	/**
	* Return element IDs, including children, that are SelectedType.SELECTED.
	*
	* @return List of element IDs, including children, that are
	* SelectedType.SELECTED.
	*/
	public List getSelectedElementIds() {
	List list = new ArrayList();
	getMatchingElementIds(list, SelectedType.SELECTED);
	return list;
	}

	/**
	* Return matching element IDs that match the typeToMatch.
	*
	* @param matchingIds
	* List of String ids we are filling
	* @param typeToMatch
	* going to match this type
	*/
	private void getMatchingElementIds(List matchingIds,
	SelectedType typeToMatch) {

	for (int i = 0; i < getNumberOfChildren(); i++) {
	getChild(i).getMatchingElementIds(matchingIds, typeToMatch);
	}
	if (getSelectedType() == typeToMatch) {
	matchingIds.add(getId());
	}
	}

	/**
	* Same idea as the clone method. Share the same images, hints, etc. of the
	* original. Just have different SelectableElements.
	*
	* @return a copy of this selectableElement
	*/
	public SelectableElement makeCopy() {
	SelectableElement selectableElement = immediateCopy(this);
	copyChildren(this, selectableElement);
	return selectableElement;
	}

	/**
	* Used by the copy method. Not suprisingly, this returns a copy of the src
	*
	* @param src
	* children will be copied from here
	* @return SelectableElement which is a copy of the src
	*/
	private SelectableElement immediateCopy(SelectableElement src) {
	SelectableElement selectableElement = new SelectableElement(
	src.getId(), src.getName(), src.getIconImageDescriptor(), src
	.getHint());
	selectableElement.setSelectedType(src.getSelectedType());
	return selectableElement;
	}

	/**
	* Used by the copy method. Not surprisingly, this copies the children of
	* src into dest.
	*
	* @param src
	* children will be copied from here
	* @param dest
	* children are copied into here
	*/
	private void copyChildren(SelectableElement src, SelectableElement dest) {
	for (int i = 0; i < src.getNumberOfChildren(); i++) {
	dest.addChild(immediateCopy(src.getChild(i)));
	copyChildren(src.getChild(i), dest.getChild(i));
	}
	}

	/**
	* Collect all the hints of the children into a list.
	*
	* @param list
	* that I am collecting the hints into.
	*/
	private void collectChildrenHints(List list) {
	Object aHint = getHint();
	if (aHint instanceof List) {
	Iterator it = ((List) aHint).iterator();
	while (it.hasNext()) {
	Object obj = it.next();
	if (!list.contains(obj))
	list.add(obj);
	}

	} else if (aHint != null) {
	if (!list.contains(aHint))
	list.add(aHint);
	}

	for (int i = 0; i < getChildren().length; i++) {
	getChild(i).collectChildrenHints(list);
	}
	}

	/**
	* Collect the types that match a list of String ids. Unlike getHints, which
	* doesn't collect children hints.
	*
	* @param list
	* List to add into
	* @param ids
	* List of String ids we are trying to match
	*/
	public void getHintsThatMatchTheseIds(List list, List ids) {
	for (int i = 0; i < getNumberOfChildren(); i++) {
	if (ids.contains(getChild(i).getId())) {
	getChild(i).collectChildrenHints(list);
	} else {
	getChild(i).getHintsThatMatchTheseIds(list, ids);
	}
	}
	}

	/**
	* Return the first element that matches the given id from the List of
	* SelectableElement objects
	*
	* @param selectableElements
	* List of SelectableElement objects to match
	* @param id
	* String id to match
	* @return the first element that matches the given id from the List of
	* SelectableElement objects or null if nothing matched
	*/
	public static SelectableElement findById(List selectableElements, String id) {
	assert null != selectableElements;
	Iterator it = selectableElements.iterator();

	while (it.hasNext()) {
	Object obj = it.next();
	assert (obj instanceof SelectableElement);

	SelectableElement selectableElement = (SelectableElement) obj;
	if (id.equals(selectableElement.getId())) {
	return selectableElement;
	}
	}

	return null;
	}

	/**
	* Return the first element that matches the given id from this
	* SelectableElement and its children
	*
	* @param theId
	* String id to match
	* @return the first element that matches the given id from this
	* SelectableElement and its children or null if nothing matched
	*/
	public SelectableElement findById(String theId) {

	assert null != theId;
	if (theId.equals(this.getId())) {
	return this;
	}

	for (int i = 0; i < getNumberOfChildren(); i++) {
	SelectableElement element = getChild(i).findById(theId);
	if (element != null)
	return element;
	}

	return null;
	}

	}