001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 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.actions;
011:
012: import org.eclipse.jface.action.Action;
013: import org.eclipse.jface.viewers.ISelection;
014: import org.eclipse.jface.viewers.ISelectionChangedListener;
015: import org.eclipse.jface.viewers.ISelectionProvider;
016: import org.eclipse.jface.viewers.IStructuredSelection;
017: import org.eclipse.jface.viewers.SelectionChangedEvent;
018: import org.eclipse.jface.viewers.StructuredSelection;
019:
020: /**
021: * The abstract superclass for actions that listen to selection changes
022: * from a particular selection provider. This implementation splits the current
023: * selection along structured/unstructured lines, providing a convenient place
024: * to monitor selection changes that require adjusting action state.
025: * <p>
026: * Subclasses must implement the following <code>IAction</code> method:
027: * <ul>
028: * <li><code>run</code> - to do the action's work</li>
029: * </ul>
030: * </p>
031: * <p>
032: * Subclasses may reimplement either of the following methods:
033: * <ul>
034: * <li><code>selectionChanged(IStructuredSelection)</code></li>
035: * <li><code>selectionChanged(ISelection)</code></li>
036: * </ul>
037: * </p>
038: */
039: public abstract class SelectionProviderAction extends Action implements
040: ISelectionChangedListener {
041:
042: /**
043: * The selection provider that is the target of this action.
044: */
045: private ISelectionProvider provider;
046:
047: /**
048: * Creates a new action with the given text that monitors selection changes
049: * within the given selection provider.
050: * The resulting action is added as a listener on the selection provider.
051: *
052: * @param provider the selection provider that will provide selection notification
053: * @param text the string used as the text for the action,
054: * or <code>null</code> if there is no text
055: */
056: protected SelectionProviderAction(ISelectionProvider provider,
057: String text) {
058: super (text);
059: this .provider = provider;
060: provider.addSelectionChangedListener(this );
061: }
062:
063: /**
064: * Disposes this action by removing it as a listener from the selection provider.
065: * This must be called by the creator of the action when the action is no longer needed.
066: */
067: public void dispose() {
068: provider.removeSelectionChangedListener(this );
069: }
070:
071: /**
072: * Returns the current selection in the selection provider.
073: *
074: * @return the current selection in the selection provider
075: */
076: public ISelection getSelection() {
077: return provider.getSelection();
078: }
079:
080: /**
081: * Returns the selection provider that is the target of this action.
082: *
083: * @return the target selection provider of this action
084: */
085: public ISelectionProvider getSelectionProvider() {
086: return provider;
087: }
088:
089: /**
090: * Returns the current structured selection in the selection provider, or an
091: * empty selection if nothing is selected or if selection does not include
092: * objects (for example, raw text).
093: *
094: * @return the current structured selection in the selection provider
095: */
096: public IStructuredSelection getStructuredSelection() {
097: ISelection selection = provider.getSelection();
098: if (selection instanceof IStructuredSelection) {
099: return (IStructuredSelection) selection;
100: } else {
101: return new StructuredSelection();
102: }
103: }
104:
105: /**
106: * Notifies this action that the given (non-structured) selection has changed
107: * in the selection provider.
108: * <p>
109: * The <code>SelectionProviderAction</code> implementation of this method
110: * does nothing. Subclasses may reimplement to react to this selection change.
111: * </p>
112: *
113: * @param selection the new selection
114: */
115: public void selectionChanged(ISelection selection) {
116: }
117:
118: /**
119: * Notifies this action that the given structured selection has changed
120: * in the selection provider.
121: * <p>
122: * The <code>SelectionProviderAction</code> implementation of this method
123: * does nothing. Subclasses may reimplement to react to this selection change.
124: * </p>
125: *
126: * @param selection the new selection
127: */
128: public void selectionChanged(IStructuredSelection selection) {
129: // Hook in subclass.
130: }
131:
132: /**
133: * The <code>SelectionProviderAction</code> implementation of this
134: * <code>ISelectionChangedListener</code> method calls
135: * <code>selectionChanged(IStructuredSelection)</code> if the selection is
136: * a structured selection but <code>selectionChanged(ISelection)</code> if it is
137: * not. Subclasses should override either of those methods method to react to
138: * selection changes.
139: */
140: public final void selectionChanged(SelectionChangedEvent event) {
141: ISelection selection = event.getSelection();
142: if (selection instanceof IStructuredSelection) {
143: selectionChanged((IStructuredSelection) selection);
144: } else {
145: selectionChanged(selection);
146: }
147: }
148: }
|