bundles/org.eclipse.jface/src/org/eclipse/jface/action/ContributionManager.java - platform/eclipse.platform.ui - Git at Google

 /*******************************************************************************
  * Copyright (c) 2000, 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.jface.action;

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

 import org.eclipse.jface.util.Policy;

 /**
  * Abstract base class for all contribution managers, and standard implementation
  * of <code>IContributionManager</code>. This class provides functionality
  * common across the specific managers defined by this framework.
  * <p>
  * This class maintains a list of contribution items and a dirty flag, both as
  * internal state. In addition to providing implementations of most
  * <code>IContributionManager</code> methods, this class automatically
  * coalesces adjacent separators, hides beginning and ending separators,
  * and deals with dynamically changing sets of contributions. When the set
  * of contributions does change dynamically, the changes are propagated
  * to the control via the <code>update</code> method, which subclasses
  * must implement.
  * </p>
  * <p>
  * Note: A <code>ContributionItem</code> cannot be shared between different
  * <code>ContributionManager</code>s.
  * </p>
  */
 public abstract class ContributionManager implements IContributionManager {

     //	Internal debug flag.
     //	protected static final boolean DEBUG = false;

     /**
      * The list of contribution items.
      */
     private List contributions = new ArrayList();

     /**
      * Indicates whether the widgets are in sync with the contributions.
      */
     private boolean isDirty = true;

     /**
      * Number of dynamic contribution items.
      */
     private int dynamicItems = 0;

     /**
      * The overrides for items of this manager
      */
     private IContributionManagerOverrides overrides;

     /**
      * Creates a new contribution manager.
      */
     protected ContributionManager() {
         // Do nothing.
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void add(IAction action) {
         add(new ActionContributionItem(action));
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void add(IContributionItem item) {
         if (allowItem(item)) {
             contributions.add(item);
             itemAdded(item);
         }
     }

     /**
      * Adds a contribution item to the start or end of the group
      * with the given name.
      *
      * @param groupName the name of the group
      * @param item the contribution item
      * @param append <code>true</code> to add to the end of the group,
      *   and <code>false</code> to add the beginning of the group
      * @exception IllegalArgumentException if there is no group with
      *   the given name
      */
     private void addToGroup(String groupName, IContributionItem item,
             boolean append) {
         int i;
         Iterator items = contributions.iterator();
         for (i = 0; items.hasNext(); i++) {
             IContributionItem o = (IContributionItem) items.next();
             if (o.isGroupMarker()) {
                 String id = o.getId();
                 if (id != null && id.equalsIgnoreCase(groupName)) {
                     i++;
                     if (append) {
                         for (; items.hasNext(); i++) {
                             IContributionItem ci = (IContributionItem) items
                                     .next();
                             if (ci.isGroupMarker())
                                 break;
                         }
                     }
                     if (allowItem(item)) {
                         contributions.add(i, item);
                         itemAdded(item);
                     }
                     return;
                 }
             }
         }
         throw new IllegalArgumentException("Group not found: " + groupName);//$NON-NLS-1$
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void appendToGroup(String groupName, IAction action) {
         addToGroup(groupName, new ActionContributionItem(action), true);
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void appendToGroup(String groupName, IContributionItem item) {
         addToGroup(groupName, item, true);
     }

     /**
      * This method allows subclasses of <code>ContributionManager</code> to prevent
      * certain items in the contributions list.  <code>ContributionManager</code>
      * will either block or allow an addition based on the result of this method
      * call.  This can be used to prevent duplication, for example.
      * @param itemToAdd The contribution item to be added; may be <code>null</code>.
      * @return <code>true</code> if the addition should be allowed;
      * <code>false</code> otherwise.  The default implementation allows all items.
      * @since 3.0
      */
     protected boolean allowItem(IContributionItem itemToAdd) {
         return true;
     }

     /**
      * Internal debug method for printing statistics about this manager
      * to <code>System.out</code>.
      */
     protected void dumpStatistics() {
         int size = 0;
         if (contributions != null)
             size = contributions.size();

         System.out.println(this.toString());
         System.out.println("   Number of elements: " + size);//$NON-NLS-1$
         int sum = 0;
         for (int i = 0; i < size; i++)
             if (((IContributionItem) contributions.get(i)).isVisible())
                 sum++;
         System.out.println("   Number of visible elements: " + sum);//$NON-NLS-1$
         System.out.println("   Is dirty: " + isDirty()); //$NON-NLS-1$
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public IContributionItem find(String id) {
         Iterator e = contributions.iterator();
         while (e.hasNext()) {
             IContributionItem item = (IContributionItem) e.next();
             String itemId = item.getId();
             if (itemId != null && itemId.equalsIgnoreCase(id))
                 return item;
         }
         return null;
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public IContributionItem[] getItems() {
         IContributionItem[] items = new IContributionItem[contributions.size()];
         contributions.toArray(items);
         return items;
     }

     /**
      * The <code>ContributionManager</code> implementation of this
      * method declared on <code>IContributionManager</code> returns
      * the current overrides. If there is no overrides it lazily creates
      * one which overrides no item state.
      *
      * @since 2.0
      */
     public IContributionManagerOverrides getOverrides() {
         if (overrides == null) {
             overrides = new IContributionManagerOverrides() {
                 public Boolean getEnabled(IContributionItem item) {
                     return null;
                 }

                 public Integer getAccelerator(IContributionItem item) {
                     return null;
                 }

                 public String getAcceleratorText(IContributionItem item) {
                     return null;
                 }

                 public String getText(IContributionItem item) {
                     return null;
                 }
             };
         }
         return overrides;
     }

     /**
      * Returns whether this contribution manager contains dynamic items.
      * A dynamic contribution item contributes items conditionally,
      * dependent on some internal state.
      *
      * @return <code>true</code> if this manager contains dynamic items, and
      *  <code>false</code> otherwise
      */
     protected boolean hasDynamicItems() {
         return (dynamicItems > 0);
     }

     /**
      * Returns the index of the item with the given id.
      * @param id The id of the item whose index is requested.
      *
      * @return <code>int</code> the index or -1 if the item is not found
      */
     public int indexOf(String id) {
         for (int i = 0; i < contributions.size(); i++) {
             IContributionItem item = (IContributionItem) contributions.get(i);
             String itemId = item.getId();
             if (itemId != null && itemId.equalsIgnoreCase(id))
                 return i;
         }
         return -1;
     }

     /**
      * Returns the index of the object in the internal structure. This is different from
      * <code>indexOf(String id)</code> since some contribution items may not have an id.
      *
      * @param item The contribution item
      * @return the index, or -1 if the item is not found
      * @since 3.0
      */
     protected int indexOf(IContributionItem item) {
         return contributions.indexOf(item);
     }

     /**
      * Insert the item at the given index.
      *
      * @param index The index to be used for insertion
      * @param item The item to be inserted
      */
     public void insert(int index, IContributionItem item) {
         if (index > contributions.size())
             throw new IndexOutOfBoundsException(
                     "inserting " + item.getId() + " at " + index); //$NON-NLS-1$ //$NON-NLS-2$
         if (allowItem(item)) {
             contributions.add(index, item);
             itemAdded(item);
         }
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void insertAfter(String ID, IAction action) {
         insertAfter(ID, new ActionContributionItem(action));
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void insertAfter(String ID, IContributionItem item) {
         IContributionItem ci = find(ID);
         if (ci == null)
             throw new IllegalArgumentException("can't find ID");//$NON-NLS-1$
         int ix = contributions.indexOf(ci);
         if (ix >= 0) {
             // System.out.println("insert after: " + ix);
             if (allowItem(item)) {
                 contributions.add(ix + 1, item);
                 itemAdded(item);
             }
         }
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void insertBefore(String ID, IAction action) {
         insertBefore(ID, new ActionContributionItem(action));
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void insertBefore(String ID, IContributionItem item) {
         IContributionItem ci = find(ID);
         if (ci == null)
             throw new IllegalArgumentException("can't find ID " + ID);//$NON-NLS-1$
         int ix = contributions.indexOf(ci);
         if (ix >= 0) {
             // System.out.println("insert before: " + ix);
             if (allowItem(item)) {
                 contributions.add(ix, item);
                 itemAdded(item);
             }
         }
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public boolean isDirty() {
         if (isDirty)
             return true;
         if (hasDynamicItems()) {
             for (Iterator iter = contributions.iterator(); iter.hasNext();) {
                 IContributionItem item = (IContributionItem) iter.next();
                 if (item.isDirty())
                     return true;
             }
         }
         return false;
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public boolean isEmpty() {
         return contributions.isEmpty();
     }

     /**
      * The given item was added to the list of contributions.
      * Marks the manager as dirty and updates the number of dynamic items, and the memento.
      */
     protected void itemAdded(IContributionItem item) {
         item.setParent(this);
         markDirty();
         if (item.isDynamic())
             dynamicItems++;
     }

     /**
      * The given item was removed from the list of contributions.
      * Marks the manager as dirty and updates the number of dynamic items.
      */
     protected void itemRemoved(IContributionItem item) {
         item.setParent(null);
         markDirty();
         if (item.isDynamic())
             dynamicItems--;
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void markDirty() {
         setDirty(true);
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void prependToGroup(String groupName, IAction action) {
         addToGroup(groupName, new ActionContributionItem(action), false);
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void prependToGroup(String groupName, IContributionItem item) {
         addToGroup(groupName, item, false);
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public IContributionItem remove(String ID) {
         IContributionItem ci = find(ID);
         if (ci == null)
             return null;
         return remove(ci);
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public IContributionItem remove(IContributionItem item) {
         if (contributions.remove(item)) {
             itemRemoved(item);
             return item;
         }
         return null;
     }

     /* (non-Javadoc)
      * Method declared on IContributionManager.
      */
     public void removeAll() {
         IContributionItem[] items = getItems();
         contributions.clear();
         for (int i = 0; i < items.length; i++) {
             IContributionItem item = items[i];
             itemRemoved(item);
         }
         dynamicItems = 0;
         markDirty();
     }

     /**
      * Replaces the item of the given identifier with another contribution item.
      * This can be used, for example, to replace large contribution items with
      * placeholders to avoid memory leaks.  If the identifier cannot be found in the
      * current list of items, then this does nothing.  If multiple occurrences are
      * found, then the replacement items is put in the first position and the other
      * positions are removed.
      * @param identifier The identifier to look for in the list of contributions;
      * should not be <code>null</code>.
      * @param replacementItem The contribution item to replace the old item; must
      * not be <code>null</code>.  Use {@link org.eclipse.jface.action.ContributionManager#remove(java.lang.String) remove} if that is what you want to do.
      * @return <code>true</code> if the given identifier can be; <code>
      * @since 3.0
      */
     public boolean replaceItem(final String identifier,
             final IContributionItem replacementItem) {
         if (identifier == null) {
             return false;
         }

         final int index = indexOf(identifier);
         if (index < 0) {
             return false; // couldn't find the item.
         }

         // Remove the old item.
         final IContributionItem oldItem = (IContributionItem) contributions
                 .get(index);
         itemRemoved(oldItem);

         // Add the new item.
         contributions.set(index, replacementItem);
         itemAdded(replacementItem); // throws NPE if (replacementItem == null)

         // Go through and remove duplicates.
         for (int i = contributions.size() - 1; i > index; i--) {
             IContributionItem item = (IContributionItem) contributions.get(i);
             if ((item != null) && (identifier.equals(item.getId()))) {
                 if (Policy.TRACE_TOOLBAR) {
                     System.out
                             .println("Removing duplicate on replace: " + identifier); //$NON-NLS-1$
                 }
                 contributions.remove(i);
                 itemRemoved(item);
             }
         }

         return true; // success
     }

     /**
      * Sets whether this manager is dirty. When dirty, the list of contributions
      * is not accurately reflected in the corresponding widgets.
      *
      * @param dirty <code>true</code> if this manager is dirty, and <code>false</code>
      *   if it is up-to-date
      */
     protected void setDirty(boolean dirty) {
         isDirty = dirty;
     }

     /**
      * Sets the overrides for this contribution manager
      *
      * @param newOverrides the overrides for the items of this manager
      * @since 2.0
      */
     public void setOverrides(IContributionManagerOverrides newOverrides) {
         overrides = newOverrides;
     }

     /**
      * An internal method for setting the order of the contribution items.
      *
      * @param items the contribution items in the specified order
      * @since 3.0
      */
     protected void internalSetItems(IContributionItem[] items) {
         contributions.clear();
         for (int i = 0; i < items.length; i++) {
             if (allowItem(items[i])) {
                 contributions.add(items[i]);
             }
         }
     }
 }
	/*******************************************************************************
	* Copyright (c) 2000, 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.jface.action;

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

	import org.eclipse.jface.util.Policy;

	/**
	* Abstract base class for all contribution managers, and standard implementation
	* of <code>IContributionManager</code>. This class provides functionality
	* common across the specific managers defined by this framework.
	* <p>
	* This class maintains a list of contribution items and a dirty flag, both as
	* internal state. In addition to providing implementations of most
	* <code>IContributionManager</code> methods, this class automatically
	* coalesces adjacent separators, hides beginning and ending separators,
	* and deals with dynamically changing sets of contributions. When the set
	* of contributions does change dynamically, the changes are propagated
	* to the control via the <code>update</code> method, which subclasses
	* must implement.
	* </p>
	* <p>
	* Note: A <code>ContributionItem</code> cannot be shared between different
	* <code>ContributionManager</code>s.
	* </p>
	*/
	public abstract class ContributionManager implements IContributionManager {

	// Internal debug flag.
	// protected static final boolean DEBUG = false;

	/**
	* The list of contribution items.
	*/
	private List contributions = new ArrayList();

	/**
	* Indicates whether the widgets are in sync with the contributions.
	*/
	private boolean isDirty = true;

	/**
	* Number of dynamic contribution items.
	*/
	private int dynamicItems = 0;

	/**
	* The overrides for items of this manager
	*/
	private IContributionManagerOverrides overrides;

	/**
	* Creates a new contribution manager.
	*/
	protected ContributionManager() {
	// Do nothing.
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void add(IAction action) {
	add(new ActionContributionItem(action));
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void add(IContributionItem item) {
	if (allowItem(item)) {
	contributions.add(item);
	itemAdded(item);
	}
	}

	/**
	* Adds a contribution item to the start or end of the group
	* with the given name.
	*
	* @param groupName the name of the group
	* @param item the contribution item
	* @param append <code>true</code> to add to the end of the group,
	* and <code>false</code> to add the beginning of the group
	* @exception IllegalArgumentException if there is no group with
	* the given name
	*/
	private void addToGroup(String groupName, IContributionItem item,
	boolean append) {
	int i;
	Iterator items = contributions.iterator();
	for (i = 0; items.hasNext(); i++) {
	IContributionItem o = (IContributionItem) items.next();
	if (o.isGroupMarker()) {
	String id = o.getId();
	if (id != null && id.equalsIgnoreCase(groupName)) {
	i++;
	if (append) {
	for (; items.hasNext(); i++) {
	IContributionItem ci = (IContributionItem) items
	.next();
	if (ci.isGroupMarker())
	break;
	}
	}
	if (allowItem(item)) {
	contributions.add(i, item);
	itemAdded(item);
	}
	return;
	}
	}
	}
	throw new IllegalArgumentException("Group not found: " + groupName);//$NON-NLS-1$
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void appendToGroup(String groupName, IAction action) {
	addToGroup(groupName, new ActionContributionItem(action), true);
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void appendToGroup(String groupName, IContributionItem item) {
	addToGroup(groupName, item, true);
	}

	/**
	* This method allows subclasses of <code>ContributionManager</code> to prevent
	* certain items in the contributions list. <code>ContributionManager</code>
	* will either block or allow an addition based on the result of this method
	* call. This can be used to prevent duplication, for example.
	* @param itemToAdd The contribution item to be added; may be <code>null</code>.
	* @return <code>true</code> if the addition should be allowed;
	* <code>false</code> otherwise. The default implementation allows all items.
	* @since 3.0
	*/
	protected boolean allowItem(IContributionItem itemToAdd) {
	return true;
	}

	/**
	* Internal debug method for printing statistics about this manager
	* to <code>System.out</code>.
	*/
	protected void dumpStatistics() {
	int size = 0;
	if (contributions != null)
	size = contributions.size();

	System.out.println(this.toString());
	System.out.println(" Number of elements: " + size);//$NON-NLS-1$
	int sum = 0;
	for (int i = 0; i < size; i++)
	if (((IContributionItem) contributions.get(i)).isVisible())
	sum++;
	System.out.println(" Number of visible elements: " + sum);//$NON-NLS-1$
	System.out.println(" Is dirty: " + isDirty()); //$NON-NLS-1$
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public IContributionItem find(String id) {
	Iterator e = contributions.iterator();
	while (e.hasNext()) {
	IContributionItem item = (IContributionItem) e.next();
	String itemId = item.getId();
	if (itemId != null && itemId.equalsIgnoreCase(id))
	return item;
	}
	return null;
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public IContributionItem[] getItems() {
	IContributionItem[] items = new IContributionItem[contributions.size()];
	contributions.toArray(items);
	return items;
	}

	/**
	* The <code>ContributionManager</code> implementation of this
	* method declared on <code>IContributionManager</code> returns
	* the current overrides. If there is no overrides it lazily creates
	* one which overrides no item state.
	*
	* @since 2.0
	*/
	public IContributionManagerOverrides getOverrides() {
	if (overrides == null) {
	overrides = new IContributionManagerOverrides() {
	public Boolean getEnabled(IContributionItem item) {
	return null;
	}

	public Integer getAccelerator(IContributionItem item) {
	return null;
	}

	public String getAcceleratorText(IContributionItem item) {
	return null;
	}

	public String getText(IContributionItem item) {
	return null;
	}
	};
	}
	return overrides;
	}

	/**
	* Returns whether this contribution manager contains dynamic items.
	* A dynamic contribution item contributes items conditionally,
	* dependent on some internal state.
	*
	* @return <code>true</code> if this manager contains dynamic items, and
	* <code>false</code> otherwise
	*/
	protected boolean hasDynamicItems() {
	return (dynamicItems > 0);
	}

	/**
	* Returns the index of the item with the given id.
	* @param id The id of the item whose index is requested.
	*
	* @return <code>int</code> the index or -1 if the item is not found
	*/
	public int indexOf(String id) {
	for (int i = 0; i < contributions.size(); i++) {
	IContributionItem item = (IContributionItem) contributions.get(i);
	String itemId = item.getId();
	if (itemId != null && itemId.equalsIgnoreCase(id))
	return i;
	}
	return -1;
	}

	/**
	* Returns the index of the object in the internal structure. This is different from
	* <code>indexOf(String id)</code> since some contribution items may not have an id.
	*
	* @param item The contribution item
	* @return the index, or -1 if the item is not found
	* @since 3.0
	*/
	protected int indexOf(IContributionItem item) {
	return contributions.indexOf(item);
	}

	/**
	* Insert the item at the given index.
	*
	* @param index The index to be used for insertion
	* @param item The item to be inserted
	*/
	public void insert(int index, IContributionItem item) {
	if (index > contributions.size())
	throw new IndexOutOfBoundsException(
	"inserting " + item.getId() + " at " + index); //$NON-NLS-1$ //$NON-NLS-2$
	if (allowItem(item)) {
	contributions.add(index, item);
	itemAdded(item);
	}
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void insertAfter(String ID, IAction action) {
	insertAfter(ID, new ActionContributionItem(action));
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void insertAfter(String ID, IContributionItem item) {
	IContributionItem ci = find(ID);
	if (ci == null)
	throw new IllegalArgumentException("can't find ID");//$NON-NLS-1$
	int ix = contributions.indexOf(ci);
	if (ix >= 0) {
	// System.out.println("insert after: " + ix);
	if (allowItem(item)) {
	contributions.add(ix + 1, item);
	itemAdded(item);
	}
	}
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void insertBefore(String ID, IAction action) {
	insertBefore(ID, new ActionContributionItem(action));
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void insertBefore(String ID, IContributionItem item) {
	IContributionItem ci = find(ID);
	if (ci == null)
	throw new IllegalArgumentException("can't find ID " + ID);//$NON-NLS-1$
	int ix = contributions.indexOf(ci);
	if (ix >= 0) {
	// System.out.println("insert before: " + ix);
	if (allowItem(item)) {
	contributions.add(ix, item);
	itemAdded(item);
	}
	}
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public boolean isDirty() {
	if (isDirty)
	return true;
	if (hasDynamicItems()) {
	for (Iterator iter = contributions.iterator(); iter.hasNext();) {
	IContributionItem item = (IContributionItem) iter.next();
	if (item.isDirty())
	return true;
	}
	}
	return false;
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public boolean isEmpty() {
	return contributions.isEmpty();
	}

	/**
	* The given item was added to the list of contributions.
	* Marks the manager as dirty and updates the number of dynamic items, and the memento.
	*/
	protected void itemAdded(IContributionItem item) {
	item.setParent(this);
	markDirty();
	if (item.isDynamic())
	dynamicItems++;
	}

	/**
	* The given item was removed from the list of contributions.
	* Marks the manager as dirty and updates the number of dynamic items.
	*/
	protected void itemRemoved(IContributionItem item) {
	item.setParent(null);
	markDirty();
	if (item.isDynamic())
	dynamicItems--;
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void markDirty() {
	setDirty(true);
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void prependToGroup(String groupName, IAction action) {
	addToGroup(groupName, new ActionContributionItem(action), false);
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void prependToGroup(String groupName, IContributionItem item) {
	addToGroup(groupName, item, false);
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public IContributionItem remove(String ID) {
	IContributionItem ci = find(ID);
	if (ci == null)
	return null;
	return remove(ci);
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public IContributionItem remove(IContributionItem item) {
	if (contributions.remove(item)) {
	itemRemoved(item);
	return item;
	}
	return null;
	}

	/* (non-Javadoc)
	* Method declared on IContributionManager.
	*/
	public void removeAll() {
	IContributionItem[] items = getItems();
	contributions.clear();
	for (int i = 0; i < items.length; i++) {
	IContributionItem item = items[i];
	itemRemoved(item);
	}
	dynamicItems = 0;
	markDirty();
	}

	/**
	* Replaces the item of the given identifier with another contribution item.
	* This can be used, for example, to replace large contribution items with
	* placeholders to avoid memory leaks. If the identifier cannot be found in the
	* current list of items, then this does nothing. If multiple occurrences are
	* found, then the replacement items is put in the first position and the other
	* positions are removed.
	* @param identifier The identifier to look for in the list of contributions;
	* should not be <code>null</code>.
	* @param replacementItem The contribution item to replace the old item; must
	* not be <code>null</code>. Use {@link org.eclipse.jface.action.ContributionManager#remove(java.lang.String) remove} if that is what you want to do.
	* @return <code>true</code> if the given identifier can be; <code>
	* @since 3.0
	*/
	public boolean replaceItem(final String identifier,
	final IContributionItem replacementItem) {
	if (identifier == null) {
	return false;
	}

	final int index = indexOf(identifier);
	if (index < 0) {
	return false; // couldn't find the item.
	}

	// Remove the old item.
	final IContributionItem oldItem = (IContributionItem) contributions
	.get(index);
	itemRemoved(oldItem);

	// Add the new item.
	contributions.set(index, replacementItem);
	itemAdded(replacementItem); // throws NPE if (replacementItem == null)

	// Go through and remove duplicates.
	for (int i = contributions.size() - 1; i > index; i--) {
	IContributionItem item = (IContributionItem) contributions.get(i);
	if ((item != null) && (identifier.equals(item.getId()))) {
	if (Policy.TRACE_TOOLBAR) {
	System.out
	.println("Removing duplicate on replace: " + identifier); //$NON-NLS-1$
	}
	contributions.remove(i);
	itemRemoved(item);
	}
	}

	return true; // success
	}

	/**
	* Sets whether this manager is dirty. When dirty, the list of contributions
	* is not accurately reflected in the corresponding widgets.
	*
	* @param dirty <code>true</code> if this manager is dirty, and <code>false</code>
	* if it is up-to-date
	*/
	protected void setDirty(boolean dirty) {
	isDirty = dirty;
	}

	/**
	* Sets the overrides for this contribution manager
	*
	* @param newOverrides the overrides for the items of this manager
	* @since 2.0
	*/
	public void setOverrides(IContributionManagerOverrides newOverrides) {
	overrides = newOverrides;
	}

	/**
	* An internal method for setting the order of the contribution items.
	*
	* @param items the contribution items in the specified order
	* @since 3.0
	*/
	protected void internalSetItems(IContributionItem[] items) {
	contributions.clear();
	for (int i = 0; i < items.length; i++) {
	if (allowItem(items[i])) {
	contributions.add(items[i]);
	}
	}
	}
	}