001: /*******************************************************************************
002: * Copyright (c) 2006, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.menus;
011:
012: import org.eclipse.jface.action.IContributionItem;
013: import org.eclipse.ui.services.IServiceLocator;
014:
015: /**
016: * ContributionFactories are used by the IMenuService to populate
017: * ContributionManagers. In {@link #createContributionItems(IServiceLocator, IContributionRoot)}
018: * you fill in the additions List with {@link IContributionItem} to be inserted at this
019: * factory's location. For example:
020: * <p>
021: *
022: * <pre>
023: * AbstractContributionFactory contributions = new AbstractContributionFactory(
024: * "menu:org.eclipse.ui.tests.api.MenuTestHarness?after=additions") {
025: * public void createContributionItems(IMenuService menuService, List additions) {
026: * CommandContributionItem item = new CommandContributionItem(
027: * "org.eclipse.ui.tests.menus.helloWorld",
028: * "org.eclipse.ui.tests.commands.enabledHelloWorld", null, null,
029: * "Say Hello", null);
030: * additions.add(item);
031: * item = new CommandContributionItem(
032: * "org.eclipse.ui.tests.menus.refresh",
033: * "org.eclipse.ui.tests.commands.refreshView", null, null,
034: * "Refresh", null);
035: * menuService.registerVisibleWhen(item, new MyActiveContextExpression(
036: * "org.eclipse.ui.tests.myview.context"));
037: * additions.add(item);
038: * }
039: *
040: * public void releaseContributionItems(IMenuService menuService, List items) {
041: * // we have nothing to do
042: * }
043: * };
044: * IMenuService service = (IMenuService) PlatformUI.getWorkbench().getService(
045: * IMenuService.class);
046: * service.addContributionFactory(contributions);
047: * </pre>
048: *
049: * </p>
050: * <p>
051: * Only the abstract methods may be implemented.
052: * </p>
053: *
054: * @since 3.3
055: * @see org.eclipse.ui.menus.IMenuService
056: * @see org.eclipse.jface.action.MenuManager
057: * @see org.eclipse.jface.action.ToolBarManager
058: */
059: public abstract class AbstractContributionFactory {
060: private String location = null;
061: private String namespace;
062:
063: /**
064: * The contribution factories must be instantiated with their location,
065: * which which specifies the contributions insertion location.
066: *
067: * @param location
068: * the addition location in Menu API URI format. It must not be
069: * <code>null</code>.
070: * @param namespace
071: * the namespace for this contribution. May be <code>null</code>.
072: * @see #getNamespace()
073: */
074: public AbstractContributionFactory(String location, String namespace) {
075: this .location = location;
076: this .namespace = namespace;
077: }
078:
079: /**
080: * Return the location as a String.
081: *
082: * @return the location - never <code>null</code>.
083: */
084: public String getLocation() {
085: return location;
086: }
087:
088: /**
089: * This factory should create the IContributionItems that it wants to
090: * contribute, and add them to the additions list. The menu service will
091: * call this method at the appropriate time. It should always return new
092: * instances of its contributions in the additions list.
093: * <p>
094: * This method is not meant to be called by clients. It will be called by
095: * the menu service at the appropriate time.
096: * </p>
097: *
098: * @param serviceLocator
099: * a service locator that may be used in the construction of
100: * items created by this factory
101: * @param additions
102: * A {@link IContributionRoot} supplied by the framework. It will
103: * never be <code>null</code>.
104: * @see org.eclipse.ui.menus.CommandContributionItem
105: * @see org.eclipse.jface.action.MenuManager
106: */
107: public abstract void createContributionItems(
108: IServiceLocator serviceLocator, IContributionRoot additions);
109:
110: /**
111: * Return the namespace for this cache. This corresponds to the plug-in that
112: * is contributing this factory.
113: *
114: * @return the namespace the namespace of this factory
115: */
116: public String getNamespace() {
117: return namespace;
118: }
119: }
|