contributionmanager.java

jfa2ce 源码帮助开发人员更好的理解运用

/*******************************************************************************
 * Copyright (c) 2000, 2006 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