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  ("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   {
99          if (query == null) {
100             throw new IllegalArgumentException  ("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   {
125         if (query == null) {
126             throw new IllegalArgumentException  ("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  ("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  ("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  ("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  ("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  ("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   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   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   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   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   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   getDefaultPerspectiveId() {
325         return SearchPreferencePage.getDefaultPerspectiveId();
326     }
327 
328 }
329
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags