KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > search > ui > NewSearchUI


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.search.ui;
12
13 import org.eclipse.search.internal.ui.OpenSearchDialogAction;
14 import org.eclipse.search.internal.ui.SearchPlugin;
15 import org.eclipse.search.internal.ui.SearchPreferencePage;
16 import org.eclipse.search2.internal.ui.InternalSearchUI;
17 import org.eclipse.search2.internal.ui.SearchMessages;
18
19 import org.eclipse.core.runtime.IStatus;
20
21 import org.eclipse.jface.dialogs.ErrorDialog;
22 import org.eclipse.jface.operation.IRunnableContext;
23
24 import org.eclipse.ui.IWorkbenchWindow;
25 /**
26  * A facade for access to the new search UI facilities.
27  *
28  * @since 3.0
29  */

30 public class NewSearchUI {
31     /**
32      * Activates a search result view in the current workbench window page. If a
33      * search view is already open in the current workbench window page, it is
34      * activated. Otherwise a new search view is opened and activated.
35      *
36      * @return the activate search result view or <code>null</code> if the
37      * search result view couldn't be activated
38      */

39     public static ISearchResultViewPart activateSearchResultView() {
40         return InternalSearchUI.getInstance().getSearchViewManager().activateSearchView(false);
41     }
42     /**
43      * Gets the search result view shown in the current workbench window.
44      *
45      * @return the search result view or <code>null</code>, if none is open
46      * in the current workbench window page
47      */

48     public static ISearchResultViewPart getSearchResultView() {
49         return InternalSearchUI.getInstance().getSearchViewManager().getActiveSearchView();
50     }
51     /**
52      * Runs the given search query. This method may run the given query in a
53      * separate thread if <code>ISearchQuery#canRunInBackground()</code>
54      * returns <code>true</code>. Running a query adds it to the set of known
55      * queries and notifies any registered <code>IQueryListener</code>s about
56      * the addition.
57      *
58      * @param query
59      * the query to execute
60      * @deprecated deprecated in 3.1.
61      * Use {@link #runQueryInBackground(ISearchQuery)} to run a query in background
62      * or {@link #runQueryInForeground(IRunnableContext, ISearchQuery)} to run it in foreground
63      */

64     public static void runQuery(ISearchQuery query) {
65         if (query == null) {
66             throw new IllegalArgumentException JavaDoc("query must not be null"); //$NON-NLS-1$
67
}
68         if (query.canRunInBackground())
69             runQueryInBackground(query);
70         else {
71             IStatus status= runQueryInForeground(null, query);
72             if (status != null) {
73                 if (!status.isOK())
74                     SearchPlugin.log(status);
75                 if (status.getSeverity() == IStatus.ERROR) {
76                     ErrorDialog.openError(SearchPlugin.getActiveWorkbenchShell(), SearchMessages.NewSearchUI_error_title, SearchMessages.NewSearchUI_error_label, status);
77                 }
78             }
79         }
80     }
81     
82     /**
83      * Runs the given search query. This method will execute the query in a
84      * background thread and not block until the search is finished.
85      * Running a query adds it to the set of known queries and notifies
86      * any registered {@link IQueryListener}s about the addition.
87      * <p>
88      * The search view that shows the result will be activated. That means a call
89      * to {@link #activateSearchResultView} is not required.
90      * </p>
91      *
92      * @param query
93      * the query to execute. The query must be able to run in background, that means
94      * {@link ISearchQuery#canRunInBackground()} must be <code>true</code>
95      * @throws IllegalArgumentException Thrown when the passed query is not able to run in background
96      * @since 3.1
97      */

98     public static void runQueryInBackground(ISearchQuery query) throws IllegalArgumentException JavaDoc {
99         if (query == null) {
100             throw new IllegalArgumentException JavaDoc("query must not be null"); //$NON-NLS-1$
101
}
102         runQueryInBackground(query, null);
103     }
104     
105     /**
106      * Runs the given search query. This method will execute the query in a
107      * background thread and not block until the search is finished.
108      * Running a query adds it to the set of known queries and notifies
109      * any registered {@link IQueryListener}s about the addition.
110      * <p>
111      * The result will be shown in the given search result view which will be activated. A call to
112      * to {@link #activateSearchResultView} is not required.
113      * </p>
114      *
115      * @param query
116      * the query to execute. The query must be able to run in background, that means
117      * {@link ISearchQuery#canRunInBackground()} must be <code>true</code>
118      * @param view
119      * the search result view to show the result in. If <code>null</code> is passed in, the default activation
120      * mechanism is used to open a new result view or to select the view to be reused.
121      * @throws IllegalArgumentException Thrown when the passed query is not able to run in background
122      * @since 3.2
123      */

124     public static void runQueryInBackground(ISearchQuery query, ISearchResultViewPart view) throws IllegalArgumentException JavaDoc {
125         if (query == null) {
126             throw new IllegalArgumentException JavaDoc("query must not be null"); //$NON-NLS-1$
127
}
128         if (query.canRunInBackground())
129             InternalSearchUI.getInstance().runSearchInBackground(query, view);
130         else
131             throw new IllegalArgumentException JavaDoc("Query can not be run in background"); //$NON-NLS-1$
132
}
133     
134     /**
135      * Runs the given search query. This method will execute the query in the
136      * same thread as the caller. This method blocks until the query is
137      * finished. Running a query adds it to the set of known queries and notifies
138      * any registered {@link IQueryListener}s about the addition.
139      * <p>
140      * The result will be shown in a search view that will be activated. That means a call
141      * to {@link #activateSearchResultView} is not required.
142      * </p>
143      *
144      * @param context
145      * the runnable context to run the query in
146      * @param query
147      * the query to execute
148      * @return a status indicating whether the query ran correctly, including {@link IStatus#CANCEL} to signal
149      * that the query was canceled.
150      */

151     public static IStatus runQueryInForeground(IRunnableContext context, ISearchQuery query) {
152         if (query == null) {
153             throw new IllegalArgumentException JavaDoc("query must not be null"); //$NON-NLS-1$
154
}
155         return runQueryInForeground(context, query, null);
156     }
157     
158     /**
159      * Runs the given search query. This method will execute the query in the
160      * same thread as the caller. This method blocks until the query is
161      * finished. Running a query adds it to the set of known queries and notifies
162      * any registered {@link IQueryListener}s about the addition.
163      * <p>
164      * The result will be shown in the given search result view which will be activated. A call to
165      * to {@link #activateSearchResultView} is not required.
166      * </p>
167      *
168      * @param context
169      * the runnable context to run the query in
170      * @param query
171      * the query to execute
172      * @param view
173      * the search result view to show the result in. If <code>null</code> is passed in, the default activation
174      * mechanism is used to open a new result view or to select the view to be reused.
175      * @return a status indicating whether the query ran correctly, including {@link IStatus#CANCEL} to signal
176      * that the query was canceled.
177      *
178      * @since 3.2
179      */

180     public static IStatus runQueryInForeground(IRunnableContext context, ISearchQuery query, ISearchResultViewPart view) {
181         if (query == null) {
182             throw new IllegalArgumentException JavaDoc("query must not be null"); //$NON-NLS-1$
183
}
184         return InternalSearchUI.getInstance().runSearchInForeground(context, query, view);
185     }
186     
187     /**
188      * Registers the given listener to receive notification of changes to
189      * queries. The listener will be notified whenever a query has been added,
190      * removed, is starting or has finished. Has no effect if an identical
191      * listener is already registered.
192      *
193      * @param l
194      * the listener to be added
195      */

196     public static void addQueryListener(IQueryListener l) {
197         InternalSearchUI.getInstance().addQueryListener(l);
198     }
199     /**
200      * Removes the given query listener. Does nothing if the listener is not
201      * present.
202      *
203      * @param l
204      * the listener to be removed.
205      */

206     public static void removeQueryListener(IQueryListener l) {
207         InternalSearchUI.getInstance().removeQueryListener(l);
208     }
209     /**
210      * Returns all search queries know to the search UI (i.e. registered via
211      * <code>runQuery()</code> or <code>runQueryInForeground())</code>.
212      *
213      * @return all search results
214      */

215     public static ISearchQuery[] getQueries() {
216         return InternalSearchUI.getInstance().getQueries();
217     }
218     
219     /**
220      * Returns whether the given query is currently running. Queries may be run
221      * by client request or by actions in the search UI.
222      *
223      * @param query
224      * the query
225      * @return whether the given query is currently running
226      * @see NewSearchUI#runQueryInBackground(ISearchQuery)
227      * @see NewSearchUI#runQueryInForeground(IRunnableContext, ISearchQuery)
228      */

229     public static boolean isQueryRunning(ISearchQuery query) {
230         if (query == null) {
231             throw new IllegalArgumentException JavaDoc("query must not be null"); //$NON-NLS-1$
232
}
233         return InternalSearchUI.getInstance().isQueryRunning(query);
234     }
235     
236     /**
237      * Sends a 'cancel' command to the given query running in background.
238      * The call has no effect if the query is not running, not in background or is not cancelable.
239      *
240      * @param query
241      * the query
242      * @since 3.1
243      */

244     public static void cancelQuery(ISearchQuery query) {
245         if (query == null) {
246             throw new IllegalArgumentException JavaDoc("query must not be null"); //$NON-NLS-1$
247
}
248         InternalSearchUI.getInstance().cancelSearch(query);
249     }
250     
251     /**
252      * Search Plug-in Id (value <code>"org.eclipse.search"</code>).
253      */

254     public static final String JavaDoc PLUGIN_ID= "org.eclipse.search"; //$NON-NLS-1$
255

256     /**
257      * Search marker type (value <code>"org.eclipse.search.searchmarker"</code>).
258      *
259      * @see org.eclipse.core.resources.IMarker
260      */

261     public static final String JavaDoc SEARCH_MARKER= PLUGIN_ID + ".searchmarker"; //$NON-NLS-1$
262

263     /**
264      * Id of the new Search view
265      * (value <code>"org.eclipse.search.ui.views.SearchView"</code>).
266      */

267     public static final String JavaDoc SEARCH_VIEW_ID= "org.eclipse.search.ui.views.SearchView"; //$NON-NLS-1$
268

269     /**
270      * Id of the Search action set
271      * (value <code>"org.eclipse.search.searchActionSet"</code>).
272      */

273     public static final String JavaDoc ACTION_SET_ID= PLUGIN_ID + ".searchActionSet"; //$NON-NLS-1$
274

275
276     /**
277      * Opens the search dialog.
278      * If <code>pageId</code> is specified and a corresponding page
279      * is found then it is brought to top.
280      * @param window the parent window
281      *
282      * @param pageId the page to select or <code>null</code>
283      * if the best fitting page should be selected
284      */

285     public static void openSearchDialog(IWorkbenchWindow window, String JavaDoc pageId) {
286         new OpenSearchDialogAction(window, pageId).run();
287     }
288
289     /**
290      * Returns the preference whether editors should be reused
291      * when showing search results.
292      *
293      * The goto action can decide to use or ignore this preference.
294      *
295      * @return <code>true</code> if editors should be reused for showing search results
296      */

297     public static boolean reuseEditor() {
298         return SearchPreferencePage.isEditorReused();
299     }
300
301     /**
302      * Returns the preference whether a search engine is
303      * allowed to report potential matches or not.
304      * <p>
305      * Search engines which can report inexact matches must
306      * respect this preference i.e. they should not report
307      * inexact matches if this method returns <code>true</code>
308      * </p>
309      * @return <code>true</code> if search engine must not report inexact matches
310      */

311     public static boolean arePotentialMatchesIgnored() {
312         return SearchPreferencePage.arePotentialMatchesIgnored();
313     }
314
315     /**
316      * Returns the ID of the default perspective.
317      * <p>
318      * The perspective with this ID will be used to show the Search view.
319      * If no default perspective is set then the Search view will
320      * appear in the current perspective.
321      * </p>
322      * @return the ID of the default perspective <code>null</code> if no default perspective is set
323      */

324     public static String JavaDoc getDefaultPerspectiveId() {
325         return SearchPreferencePage.getDefaultPerspectiveId();
326     }
327
328 }
329
Popular Tags