/*******************************************************************************
* Copyright (c) 2006, 2007 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.menus;
import org.eclipse.jface.action.IContributionItem;
import org.eclipse.ui.services.IServiceLocator;
/**
* ContributionFactories are used by the IMenuService to populate
* ContributionManagers. In {@link #createContributionItems(IServiceLocator, IContributionRoot)}
* you fill in the additions List with {@link IContributionItem} to be inserted at this
* factory's location. For example:
* <p>
*
* <pre>
* AbstractContributionFactory contributions = new AbstractContributionFactory(
* "menu:org.eclipse.ui.tests.api.MenuTestHarness?after=additions") {
* public void createContributionItems(IMenuService menuService, List additions) {
* CommandContributionItem item = new CommandContributionItem(
* "org.eclipse.ui.tests.menus.helloWorld",
* "org.eclipse.ui.tests.commands.enabledHelloWorld", null, null,
* "Say Hello", null);
* additions.add(item);
* item = new CommandContributionItem(
* "org.eclipse.ui.tests.menus.refresh",
* "org.eclipse.ui.tests.commands.refreshView", null, null,
* "Refresh", null);
* menuService.registerVisibleWhen(item, new MyActiveContextExpression(
* "org.eclipse.ui.tests.myview.context"));
* additions.add(item);
* }
*
* public void releaseContributionItems(IMenuService menuService, List items) {
* // we have nothing to do
* }
* };
* IMenuService service = (IMenuService) PlatformUI.getWorkbench().getService(
* IMenuService.class);
* service.addContributionFactory(contributions);
* </pre>
*
* </p>
* <p>
* Only the abstract methods may be implemented.
* </p>
*
* @since 3.3
* @see org.eclipse.ui.menus.IMenuService
* @see org.eclipse.jface.action.MenuManager
* @see org.eclipse.jface.action.ToolBarManager
*/
public abstract class AbstractContributionFactory {
private String location = null;
private String namespace;
/**
* The contribution factories must be instantiated with their location,
* which which specifies the contributions insertion location.
*
* @param location
* the addition location in Menu API URI format. It must not be
* <code>null</code>.
* @param namespace
* the namespace for this contribution. May be <code>null</code>.
* @see #getNamespace()
*/
public AbstractContributionFactory(String location, String namespace) {
this.location = location;
this.namespace = namespace;
}
/**
* Return the location as a String.
*
* @return the location - never <code>null</code>.
*/
public String getLocation() {
return location;
}
/**
* This factory should create the IContributionItems that it wants to
* contribute, and add them to the additions list. The menu service will
* call this method at the appropriate time. It should always return new
* instances of its contributions in the additions list.
* <p>
* This method is not meant to be called by clients. It will be called by
* the menu service at the appropriate time.
* </p>
*
* @param serviceLocator
* a service locator that may be used in the construction of
* items created by this factory
* @param additions
* A {@link IContributionRoot} supplied by the framework. It will
* never be <code>null</code>.
* @see org.eclipse.ui.menus.CommandContributionItem
* @see org.eclipse.jface.action.MenuManager
*/
public abstract void createContributionItems(IServiceLocator serviceLocator,
IContributionRoot additions);
/**
* Return the namespace for this cache. This corresponds to the plug-in that
* is contributing this factory.
*
* @return the namespace the namespace of this factory
*/
public String getNamespace() {
return namespace;
}
}