Added some function documentation (explode, rege, eregi,...)
[phpeclipse.git] / net.sourceforge.phpeclipse / src / net / sourceforge / phpdt / internal / ui / actions / SelectionDispatchAction.java
1 /*******************************************************************************
2  * Copyright (c) 2002 International Business Machines Corp. and others.
3  * All rights reserved. This program and the accompanying materials 
4  * are made available under the terms of the Common Public License v0.5 
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/cpl-v05.html
7  * 
8  * Contributors:
9  *     IBM Corporation - initial API and implementation
10  ******************************************************************************/
11 package net.sourceforge.phpdt.internal.ui.actions;
12
13 import org.eclipse.swt.widgets.Shell;
14
15 import org.eclipse.jface.action.Action;
16 import org.eclipse.jface.text.ITextSelection;
17 import org.eclipse.jface.util.Assert;
18 import org.eclipse.jface.viewers.ISelection;
19 import org.eclipse.jface.viewers.ISelectionChangedListener;
20 import org.eclipse.jface.viewers.ISelectionProvider;
21 import org.eclipse.jface.viewers.IStructuredSelection;
22 import org.eclipse.jface.viewers.SelectionChangedEvent;
23
24 import org.eclipse.ui.IWorkbenchSite;
25
26 /**
27  * Action that dispatches the <code>IAction#run()</code> and the 
28  * <code>ISelectionChangedListener#selectionChanged</code> 
29  * according to the type of the selection. 
30  * 
31  * <ul>
32  *      <li>if selection is of type <code>ITextSelection</code> then
33  *      <code>run(ITextSelection)</code> and <code>selectionChanged(ITextSelection)</code>
34  *      is called.</li> 
35  *      <li>if selection is of type <code>IStructuredSelection</code> then
36  *      <code>run(IStructuredSelection)</code> and <code>
37  *      selectionChanged(IStructuredSelection)</code> is called.</li>
38  *      <li>default is to call <code>run(ISelection)</code> and <code>
39  *      selectionChanged(ISelection)</code>.</li>
40  * </ul>
41  * 
42  * <p>
43  * Note: This class is not intended to be subclassed outside the JDT UI plugin.
44  * </p>
45  * 
46  * @since 2.0
47  */
48 public abstract class SelectionDispatchAction extends Action implements ISelectionChangedListener {
49         
50         private IWorkbenchSite fSite;
51         
52         /**
53          * Creates a new action with no text and no image.
54          * <p>
55          * Configure the action later using the set methods.
56          * </p>
57          * 
58          * @param site the site this action is working on
59          */
60         protected SelectionDispatchAction(IWorkbenchSite site) {
61                 Assert.isNotNull(site);
62                 fSite= site;
63         }
64
65         /**
66          * Returns the site owning this action.
67          * 
68          * @return the site owning this action
69          */
70         public IWorkbenchSite getSite() {
71                 return fSite;
72         }
73
74         /**
75          * Returns the selection provided by the site owning this action.
76          * 
77          * @return the site's selection
78          */     
79         public ISelection getSelection() {
80                 return getSelectionProvider().getSelection();
81         }
82
83         /**
84          * Returns the shell provided by the site owning this action.
85          * 
86          * @return the site's shell     
87          */
88         public  Shell getShell() {
89                 return fSite.getShell();
90         }
91         
92         /**
93          * Returns the selection provider managed by the site owning this action.
94          * 
95          * @return the site's selection provider        
96          */
97         public ISelectionProvider getSelectionProvider() {
98                 return fSite.getSelectionProvider();
99         }
100
101         /**
102          * Updates the action's enablement state according to the given selection. This
103          * default implementation calls one of the <code>selectionChanged</code>
104          * methods depending on the type of the passed selection.
105          * 
106          * @param selection the selection this action is working on
107          */
108         public void update(ISelection selection) {
109                 dispatchSelectionChanged(selection);
110         }
111
112         /**
113          * Notifies this action that the given structured selection has changed. This default
114          * implementation calls <code>selectionChanged(ISelection selection)</code>.
115          * 
116          * @param selection the new selection
117          */
118         protected void selectionChanged(IStructuredSelection selection) {
119                 selectionChanged((ISelection)selection);
120         }
121
122         /**
123          * Executes this actions with the given structured selection. This default implementation
124          * calls <code>run(ISelection selection)</code>.
125          */
126         protected void run(IStructuredSelection selection) {
127                 run((ISelection)selection);
128         }
129         
130         /**
131          * Notifies this action that the given text selection has changed.  This default
132          * implementation calls <code>selectionChanged(ISelection selection)</code>.
133          * 
134          * @param selection the new selection
135          */
136         protected void selectionChanged(ITextSelection selection) {
137                 selectionChanged((ISelection)selection);
138         }
139         
140         /**
141          * Executes this actions with the given text selection. This default implementation
142          * calls <code>run(ISelection selection)</code>.
143          */
144         protected void run(ITextSelection selection) {
145                 run((ISelection)selection);
146         }
147         
148         /**
149          * Notifies this action that the given selection has changed.  This default
150          * implementation sets the action's enablement state to <code>false</code>.
151          * 
152          * @param selection the new selection
153          */
154         protected void selectionChanged(ISelection selection) {
155                 setEnabled(false);
156         }
157         
158         /**
159          * Executes this actions with the given selection. This default implementation
160          * does nothing.
161          */
162         protected void run(ISelection selection) {
163         }
164
165         /* (non-Javadoc)
166          * Method declared on IAction.
167          */
168         public void run() {
169                 dispatchRun(getSelection());
170         }
171         
172         /* (non-Javadoc)
173          * Method declared on ISelectionChangedListener.
174          */
175         public void selectionChanged(SelectionChangedEvent event) {
176                 dispatchSelectionChanged(event.getSelection());
177         }
178
179         private void dispatchSelectionChanged(ISelection selection) {
180                 if (selection instanceof IStructuredSelection) {
181                         selectionChanged((IStructuredSelection)selection);
182                 } else if (selection instanceof ITextSelection) {
183                         selectionChanged((ITextSelection)selection);
184                 } else {
185                         selectionChanged(selection);
186                 }
187         }
188
189         private void dispatchRun(ISelection selection) {
190                 if (selection instanceof IStructuredSelection) {
191                         run((IStructuredSelection)selection);
192                 } else if (selection instanceof ITextSelection) {
193                         run((ITextSelection)selection);
194                 } else {
195                         run(selection);
196                 }
197         }
198 }