01: /*******************************************************************************
02: * Copyright (c) 2000, 2006 IBM Corporation and others.
03: * All rights reserved. This program and the accompanying materials
04: * are made available under the terms of the Eclipse Public License v1.0
05: * which accompanies this distribution, and is available at
06: * http://www.eclipse.org/legal/epl-v10.html
07: *
08: * Contributors:
09: * IBM Corporation - initial API and implementation
10: *******************************************************************************/package org.eclipse.ui;
11:
12: import org.eclipse.jface.action.IAction;
13: import org.eclipse.jface.viewers.ISelection;
14:
15: /**
16: * Interface for actions contributed via an extension point.
17: * <p>
18: * This interface should be implemented by clients who need to contribute actions
19: * via an extension point. The workbench will generate a <b>proxy action</b>
20: * object on behalf of the plug-in to avoid having to activate the plug-in until
21: * the user needs it. If the action is performed the workbench will load the class
22: * that implements this interface and create what is called an <b>action
23: * delegate</b> object. Then the request, and all subsequent ones, are
24: * forwarded through the proxy action to the action delegate, which does the
25: * real work.
26: * </p><p>
27: * The proxy action is the one that appears in the UI, so the action delegate
28: * will need to talk to the proxy action in order to keep up an appropriate
29: * appearance. Once the action delegate has been created, it will be
30: * notified of all selection changes, allowing it to enable or disable the
31: * proxy action appropriately.
32: * </p><p>
33: * An action delegate cannot be consulted about selection changes before the
34: * action is performed because it does not exist. For this reason, control of
35: * the action's enable state should also be exercised through simple XML rules
36: * contained in the extension. These rules allow enable state control before
37: * the action delegate's plug-in is loaded.
38: * </p><p>
39: * Clients can choose to subclass the provided abstract implementation
40: * <code>org.eclipse.ui.actions.ActionDelegate</code> or implement the
41: * interface directly.
42: * </p>
43: *
44: * @see org.eclipse.ui.actions.ActionDelegate
45: * @see org.eclipse.ui.IActionDelegate2
46: */
47: public interface IActionDelegate {
48: /**
49: * Performs this action.
50: * <p>
51: * This method is called by the proxy action when the action has been
52: * triggered. Implement this method to do the actual work.
53: * </p><p>
54: * <b>Note:</b> If the action delegate also implements
55: * <code>IActionDelegate2</code>, then this method is not invoked but
56: * instead the <code>runWithEvent(IAction, Event)</code> method is called.
57: * </p>
58: *
59: * @param action the action proxy that handles the presentation portion of the
60: * action
61: */
62: public void run(IAction action);
63:
64: /**
65: * Notifies this action delegate that the selection in the workbench has changed.
66: * <p>
67: * Implementers can use this opportunity to change the availability of the
68: * action or to modify other presentation properties.
69: * </p><p>
70: * When the selection changes, the action enablement state is updated based on
71: * the criteria specified in the plugin.xml file. Then the delegate is notified
72: * of the selection change regardless of whether the enablement criteria in the
73: * plugin.xml file is met.
74: * </p>
75: *
76: * @param action the action proxy that handles presentation portion of
77: * the action
78: * @param selection the current selection, or <code>null</code> if there
79: * is no selection.
80: */
81: public void selectionChanged(IAction action, ISelection selection);
82: }
|