/*******************************************************************************
 * 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.ui;

import org.eclipse.jface.action.IAction;
import org.eclipse.jface.action.IMenuManager;
import org.eclipse.jface.action.IStatusLineManager;
import org.eclipse.jface.action.IToolBarManager;
import org.eclipse.ui.services.IServiceLocator;

/**
 * Used by a part to access its menu, toolbar, and status line managers.  
 * <p>
 * Within the workbench each part, editor or view, has a private set of action
 * bars.  This set, which contains a menu, toolbar, and status line, appears
 * in the local toolbar for a view and in the window for an editor.  The view
 * may provide an implementation for pre-existing actions or add new actions to
 * the action bars.
 * </p>

 * In a workbench window there are a number of actions which are applicable to
 * all parts.  Some common examples are <code>CUT, COPY and 
 * <code>PASTE. These actions, known as "global actions", are contributed to 
 * the workbench window by the window itself and shared by all parts.  The
 * presentation is owned by the window.  The implementation is delegated to the
 * active part.  
 * </p>

 * To participate in the global action design an <code>IWorkbenchPart should 
 * register a handler for each global action which is implemented by the part.  This 
 * can be done by calling <code>setGlobalActionHandler.  For convenience, the 
 * standard global actions are defined in 
 * <code>org.eclipse.ui.IWorkbenchActionConstants. 
 * </p>

 * Additional work is required for the <code>Delete global action.  In
 * this case the accelerator is defined in the menu item text but is not hooked 
 * on the window.  This is to support text editors where the <code>Delete 
 * key is functional even when the <code>Delete action is disabled (no text 
 * is selected).  An implementation for this accelerator must be defined locally, 
 * in each part, by listening for <code>Delete key events.
 * </p>

 * A part may also contribute new actions to the action bars as required.  To do
 * this, call <code>getMenuManager, getToolBarManager, or
 * <code>getStatusLineManager as appropriate to get the action target.
 * Add the action(s) to the target and call <code>update to commit
 * any changes to the underlying widgets.
 * </p>

 * This interface is not intended to be implemented by clients.
 * </p>
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IActionBars {
    /**
     * Clears the global action handler list.
     * <p>
     * Note: Clients who manipulate the global action list are
     * responsible for calling <code>updateActionBars so that the changes
     * can be propagated throughout the workbench.
     * </p>
     */
    public void clearGlobalActionHandlers();

    /**
     * Returns the global action handler for the action with the given id.  
     *
     * @param actionId an action id declared in the registry
     * @return an action handler which implements the action id, or
     *	 <code>null if none is registered
     * @see IWorkbenchActionConstants
     * @see #setGlobalActionHandler(String, IAction)
     */
    public IAction getGlobalActionHandler(String actionId);

    /**
     * Returns the menu manager.
     * <p>
     * Note: Clients who add or remove items from the returned menu manager are
     * responsible for calling <code>updateActionBars so that the changes
     * can be propagated throughout the workbench.
     * </p>
     *
     * @return the menu manager
     */
    public IMenuManager getMenuManager();
    
    /**
	 * Returns the service locator for these action bars. The locator is found
	 * by looking locally, and then ascending the action bar hierarchy.
	 * 
	 * @return The service locator; never <code>null.
	 * @since 3.2
	 */
	public IServiceLocator getServiceLocator();

    /**
	 * Returns the status line manager.
	 * <p>
	 * Note: Clients who add or remove items from the returned status line
	 * manager are responsible for calling <code>updateActionBars so
	 * that the changes can be propagated throughout the workbench.
	 * </p>
	 * 
	 * @return the status line manager
	 */
    public IStatusLineManager getStatusLineManager();

    /**
     * Returns the tool bar manager.
     * <p>
     * Note: Clients who add or remove items from the returned tool bar manager are
     * responsible for calling <code>updateActionBars so that the changes
     * can be propagated throughout the workbench.
     * </p>
     *
     * @return the tool bar manager
     */
    public IToolBarManager getToolBarManager();

    /**
     * Sets the global action handler for the action with the given id.
     * <p>
     * Note: Clients who manipulate the global action list are
     * responsible for calling <code>updateActionBars so that the changes
     * can be propagated throughout the workbench.
     * </p>
     *
     * @param actionId an action id declared in the registry
     * @param handler an action which implements the action id, or
     *	<code>null to clear any existing handler
     * @see IWorkbenchActionConstants
     */
    public void setGlobalActionHandler(String actionId, IAction handler);

    /**
     * Updates the action bars.
     * <p>
     * Clients who add or remove items from the menu, tool bar, or status line
     * managers should call this method to propagated the changes throughout 
     * the workbench.
     * </p>
     */
    public void updateActionBars();
}