Java tutorial
/* * Copyright 2008 Google Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); you may not * use this file except in compliance with the License. You may obtain a copy of * the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the * License for the specific language governing permissions and limitations under * the License. */ package com.google.gwt.search.client; import com.google.gwt.core.client.GWT; import com.google.gwt.core.client.JavaScriptObject; import com.google.gwt.core.client.JsArray; import com.google.gwt.search.client.SearchCompleteHandler.SearchCompleteEvent; import com.google.gwt.search.client.impl.GSearchControl; import com.google.gwt.search.client.impl.GsearcherOptions; import com.google.gwt.search.client.impl.KeepCallback; import com.google.gwt.search.client.impl.SearchControlCompleteCallback; import com.google.gwt.search.client.impl.SearchStartingCallback; import com.google.gwt.user.client.ui.Composite; import com.google.gwt.user.client.ui.SimplePanel; /** * Encapsulates the Google Ajax Search API search control. */ public class SearchControl extends Composite { private static final GSearchControl SEARCH_CONTROL = GWT.create(GSearchControl.class); /** * Enables the SearchControl facade to be used as a return type through JSIO * interfaces. * * @throws RuntimeException because this should never be called. */ static SearchControl createPeer(JavaScriptObject obj) { /* * The reason that this is as failure is because it would only ever be * invoked if a GSearchControl-JSO were being returned from a JSIO method * without having been previously bound to a SearchControl facade. Because * we do not expose the GSearchControl API, there should never be a instance * where an unbound GSearchControl is passed through this API. */ throw new RuntimeException("SearchControl.createPeer() unimplemented."); } /** * The backing JSO, named per JSIO spec. */ private final JavaScriptObject jsoPeer = SEARCH_CONTROL.construct(); /** * Retains all KeepHandlers that should be notified when the user clicks on * the "keep" link in the SearchControl. */ private final KeepHandlerCollection keepHandlers = new KeepHandlerCollection(); /** * Retains all {@link SearchResultsHandler}s that should be notified when the * SearchControl receives Result. */ private final SearchResultsHandlerCollection resultHandlers = new SearchResultsHandlerCollection(); /** * Retains all SearchStartingHandlers that should be notified when the search * begins. */ private final SearchStartingHandlerCollection startingHandlers = new SearchStartingHandlerCollection(); /** * Constructs a new SearchControl. * * @param options Provides a configuration for displaying and executing the * SearchControl's searches */ public SearchControl(SearchControlOptions options) { SimplePanel contents = new SimplePanel(); initWidget(contents); setStyleName("gwt-SearchControl"); // Associate the backing JSO with this facade object. SEARCH_CONTROL.bind(jsoPeer, this); // Wire up the search callback every time SEARCH_CONTROL.setSearchCompleteCallback(this, null, new SearchControlCompleteCallback() { @Override public void onSearchResult(SearchControl control, Search search) { assert control == SearchControl.this; JsArray<? extends Result> results = search.getResults(); resultHandlers.fireResult(search, results); } }); // Wire up the search starting callback every time SEARCH_CONTROL.setSearchStartingCallback(this, null, new SearchStartingCallback() { @Override public void onSearchStart(SearchControl control, Search search, String query) { assert control == SearchControl.this; startingHandlers.fireResult(control, search, query); } }); // If no keep label is explicitly set, don't bother wiring up the callback. if (options.keepLabel != null) { KeepCallback keepCallback = new KeepCallback() { @Override public void onKeep(Result result) { keepHandlers.fireKeep(SearchControl.this, result); } }; // keepLabel may be either a String or a KeepLabel if (options.keepLabel instanceof String) { SEARCH_CONTROL.setOnKeepCallback(this, null, keepCallback, (String) options.keepLabel); } else if (options.keepLabel instanceof KeepLabel) { SEARCH_CONTROL.setOnKeepCallback(this, null, keepCallback, ((KeepLabel) options.keepLabel).getValue()); } } // Explicitly set the linkTarget if one is defined. if (options.linkTarget != null) { SEARCH_CONTROL.setLinkTarget(this, options.linkTarget.getValue()); } // Set the timeoutInterval if necessary if (options.timeoutInterval != null) { SEARCH_CONTROL.setTimeoutInterval(this, options.timeoutInterval.getValue()); } // Add all Searches to the control for (Search search : options.searchers) { GsearcherOptions searchOptions = options.searcherOptions.get(search); SEARCH_CONTROL.addSearcher(this, search, searchOptions); } // Build the UI. SEARCH_CONTROL.draw(this, contents.getElement(), options.drawOptions); } /** * Adds a {@link KeepHandler} to the {@link SearchControl}. It is necessary to * have set a keep label by invoking * {@link SearchControlOptions#setKeepLabel(java.lang.String)} in order to * display the keep link on the SearchControl. * * @param handler A {@link KeepHandler} that will receive notifications when * the user clicks on a keep link in the {@link SearchControl} */ public void addKeepHandler(KeepHandler handler) { keepHandlers.add(handler); } /** * Adds a {@link SearchCompleteHandler} to receive notification of all search * results loaded by the SearchControl. A SearchCompleteHandler added to the * SearchControl will receive Result objects from all Search objects added to * the SearchControl. * * @param handler A {@link SearchCompleteHandler} that will receive * notifications when the SearchControl has received a Result. * @deprecated use {@link #addSearchResultsHandler(SearchResultsHandler)} */ @Deprecated public void addSearchCompleteHandler(final SearchCompleteHandler handler) { // Delegate to addSehandler resultHandlers.add(new SearchResultsHandler() { public void onSearchResults(SearchResultsEvent event) { JsArray<? extends Result> results = event.getResults(); for (int i = 0, length = results.length(); i < length; ++i) { handler.onSearchComplete(new SearchCompleteEvent(event.getSearch(), results.get(i))); } } }); } /** * Adds a {@link SearchResultsHandler} to receive notification of all search * results loaded by the SearchControl. A SearchCompleteHandler added to the * SearchControl will receive Result objects from all Search objects added to * the SearchControl. * * @param handler A {@link SearchResultsHandler} that will receive * notifications when the SearchControl has received a Result. */ public void addSearchResultsHandler(SearchResultsHandler handler) { resultHandlers.add(handler); } /** * Adds a {@link SearchStartingHandler} to inform the search control that the * caller would like to be notified when a search starts. * * @param handler a {@link SearchStartingHandler} that will receive * notifications when the user invokes a search. */ public void addSearchStartingHandler(SearchStartingHandler handler) { startingHandlers.add(handler); } /** * Programmatically execute a query. This allows the control to be seeded with * an initial query and search results. Using this method is equivalent to * typing a query into the SearchControl and pressing return. * * @param query A search query */ public void execute(String query) { SEARCH_CONTROL.execute(this, query); } /** * Removes a KeepHandler from the SearchControl. Removing all KeepHandlers * will not remove the keep links from the displayed SearchControl. * * @param handler The KeepHandler to remove */ public void removeKeepHandler(KeepHandler handler) { keepHandlers.remove(handler); } /** * Removes a {@link SearchCompleteHandler} from the {@link SearchControl}. * * @param handler The {@link SearchCompleteHandler} to remove * @deprecated */ @Deprecated public void removeSearchCompleteHandler(SearchCompleteHandler handler) { // now a no-op... Too much trouble to implement and I think its seldomly used. } /** * Removes a {@link SearchResultsHandler} from the {@link SearchControl}. * * @param handler The {@link SearchResultsHandler} to remove */ public void removeSearchResultsHandler(SearchResultsHandler handler) { resultHandlers.remove(handler); } /** * Removes a {@link SearchStartingHandler} from the SearchControl. * * @param handler The {@link SearchStartingHandler} to remove */ public void removeSearchStartingHandler(SearchStartingHandler handler) { startingHandlers.remove(handler); } }