org.eclipse.jface.action.IContributionManager Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.jface Show documentation
This is org.eclipse.jface jar used by Scout SDK
The newest version!
/*******************************************************************************
 * Copyright (c) 2000, 2015 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;

/**
 * A contribution manager organizes contributions to such UI components
 * as menus, toolbars and status lines.
 * 
 * A contribution manager keeps track of a list of contribution
 * items. Each contribution item may has an optional identifier, which can be used
 * to retrieve items from a manager, and for positioning items relative to
 * each other. The list of contribution items can be subdivided into named groups
 * using special contribution items that serve as group markers.
 * 
 * 
 * The IContributionManager interface provides general
 * protocol for adding, removing, and retrieving contribution items.
 * It also provides convenience methods that make it convenient
 * to contribute actions. This interface should be implemented
 * by all objects that wish to manage contributions.
 * 
 * 
 * There are several implementions of this interface in this package,
 * including ones for menus ({@link MenuManager MenuManager}),
 * tool bars ({@link ToolBarManager ToolBarManager}),
 * and status lines ({@link StatusLineManager StatusLineManager}).
 * 
 */
public interface IContributionManager {
    /**
     * Adds an action as a contribution item to this manager.
     * Equivalent to add(new ActionContributionItem(action)).
     *
     * @param action the action, this cannot be null
     */
    public void add(IAction action);

    /**
     * Adds a contribution item to this manager.
     *
     * @param item the contribution item, this cannot be null
     */
    public void add(IContributionItem item);

    /**
     * Adds a contribution item for the given action at the end of the group
     * with the given name.
     * Equivalent to
     * appendToGroup(groupName,new ActionContributionItem(action)).
     *
     * @param groupName the name of the group
     * @param action the action
     * @exception IllegalArgumentException if there is no group with
     *   the given name
     */
    public void appendToGroup(String groupName, IAction action);

    /**
     * Adds a contribution item to this manager at the end of the group
     * with the given name.
     *
     * @param groupName the name of the group
     * @param item the contribution item
     * @exception IllegalArgumentException if there is no group with
     *   the given name
     */
    public void appendToGroup(String groupName, IContributionItem item);

    /**
     * Finds the contribution item with the given id.
     *
     * @param id the contribution item id
     * @return the contribution item, or null if
     *   no item with the given id can be found
     */
    public IContributionItem find(String id);

    /**
     * Returns all contribution items known to this manager.
     *
     * @return a list of contribution items
     */
    public IContributionItem[] getItems();

    /**
     * Returns the overrides for the items of this manager.
     *
     * @return the overrides for the items of this manager
     * @since 2.0
     */
    public IContributionManagerOverrides getOverrides();

    /**
     * Inserts a contribution item for the given action after the item
     * with the given id.
     * Equivalent to
     * insertAfter(id,new ActionContributionItem(action)).
     *
     * @param id the contribution item id
     * @param action the action to insert
     * @exception IllegalArgumentException if there is no item with
     *   the given id
     */
    public void insertAfter(String id, IAction action);

    /**
     * Inserts a contribution item after the item with the given id.
     *
     * @param id the contribution item id
     * @param item the contribution item to insert
     * @exception IllegalArgumentException if there is no item with
     *   the given id
     */
    public void insertAfter(String id, IContributionItem item);

    /**
     * Inserts a contribution item for the given action before the item
     * with the given id.
     * Equivalent to
     * insertBefore(id,new ActionContributionItem(action)).
     *
     * @param id the contribution item id
     * @param action the action to insert
     * @exception IllegalArgumentException if there is no item with
     *   the given id
     */
    public void insertBefore(String id, IAction action);

    /**
     * Inserts a contribution item before the item with the given id.
     *
     * @param id the contribution item id
     * @param item the contribution item to insert
     * @exception IllegalArgumentException if there is no item with
     *   the given id
     */
    public void insertBefore(String id, IContributionItem item);

    /**
     * Returns whether the list of contributions has recently changed and
     * has yet to be reflected in the corresponding widgets.
     *
     * @return true if this manager is dirty, and false
     *   if it is up-to-date
     */
    public boolean isDirty();

    /**
     * Returns whether this manager has any contribution items.
     *
     * @return true if there are no items, and
     *   false otherwise
     */
    public boolean isEmpty();

    /**
     * Marks this contribution manager as dirty.
     */
    public void markDirty();

    /**
     * Adds a contribution item for the given action at the beginning of the
     * group with the given name.
     * Equivalent to
     * prependToGroup(groupName,new ActionContributionItem(action)).
     *
     * @param groupName the name of the group
     * @param action the action
     * @exception IllegalArgumentException if there is no group with
     *   the given name
     */
    public void prependToGroup(String groupName, IAction action);

    /**
     * Adds a contribution item to this manager at the beginning of the
     * group with the given name.
     *
     * @param groupName the name of the group
     * @param item the contribution item
     * @exception IllegalArgumentException if there is no group with
     *   the given name
     */
    public void prependToGroup(String groupName, IContributionItem item);

    /**
     * Removes and returns the contribution item with the given id from this manager.
     * Returns null if this manager has no contribution items
     * with the given id.
     *
     * @param id the contribution item id
     * @return the item that was found and removed, or null if none
     */
    public IContributionItem remove(String id);

    /**
     * Removes the given contribution item from the contribution items
     * known to this manager.
     *
     * @param item the contribution item
     * @return the item parameter if the item was removed,
     *   and null if it was not found
     */
    public IContributionItem remove(IContributionItem item);

    /**
     * Removes all contribution items from this manager.
     * 
     * Note: The items will not get disposed.
     * 
     */
    public void removeAll();

    /**
     * Updates this manager's underlying widget(s) with any changes which
     * have been made to it or its items.  Normally changes to a contribution
     * manager merely mark it as dirty, without updating the underlying widgets.
     * This brings the underlying widgets up to date with any changes.
     *
     * @param force true means update even if not dirty,
     *   and false for normal incremental updating
     */
    public void update(boolean force);
}