SearchWidget.java

/*
 * This is part of Geomajas, a GIS framework, http://www.geomajas.org/.
 *
 * Copyright 2008-2015 Geosparc nv, http://www.geosparc.com/, Belgium.
 *
 * The program is available in open source according to the GNU Affero
 * General Public License. All contributions in this program are covered
 * by the Geomajas Contributors License Agreement. For full licensing
 * details, see LICENSE.txt in the project root.
 */
package org.geomajas.widget.searchandfilter.client.widget.search;

import org.geomajas.annotation.Api;
import org.geomajas.widget.searchandfilter.client.widget.search.FavouritesController.FavouriteEvent;
import org.geomajas.widget.searchandfilter.search.dto.Criterion;

/**
 * Interface with common methods needed to build a search widget.
 *
 * @see SearchWidgetRegistry
 * @author Kristof Heirwegh
 * @since 1.0.0
 */
@Api(allMethods = true)
public interface SearchWidget {

	/**
	 * Get search widget id.
	 *
	 * @return search widget id
	 */
	String getSearchWidgetId();

	/**
	 * Name of the search widget (generally I18N name).
	 *
	 * @return name of search (to be used on buttons and such).
	 */
	String getName();

	/**
	 * Show your widget for user interaction, with a search button.
	 */
	void showForSearch();

	/**
	 * Show your widget for user interaction, with a save button.
	 * @param handler A one-off callback to use when the user presses Save.
	 */
	void showForSave(SaveRequestHandler handler);

	/**
	 * Add search request handler.
	 *
	 * @param handler search request handler
	 */
	void addSearchRequestHandler(SearchRequestHandler handler);

	/**
	 * Remove search request handler.
	 *
	 * @param handler handler to remove
	 */
	void removeSearchRequestHandler(SearchRequestHandler handler);

	/**
	 * Add save request handler.
	 *
	 * @param handler handler to add
	 */
	void addSaveRequestHandler(SaveRequestHandler handler);

	/**
	 * Remove save request handler.
	 *
	 * @param handler handler to remove
	 */
	void removeSaveRequestHandler(SaveRequestHandler handler);

	/**
	 * Add favourites request handler.
	 *
	 * @param handler request handler to add
	 */
	void addFavouriteRequestHandler(FavouriteRequestHandler handler);

	/**
	 * Remove favourites request handler.
	 *
	 * @param handler request handler to remove
	 */
	void removeFavouriteRequestHandler(FavouriteRequestHandler handler);

	/**
	 * Convenience method so you don't have to add an event listener to the search system.
	 * <p>
	 * Called when search starts.
	 * <p>
	 * This allows you to show some interaction in the gui. (for example show a
	 * spinner animation)
	 */
	void onSearchStart();

	/**
	 * Convenience method so you don't have to add an event listener to the search system.
	 * <p>
	 * Called when search finished and result was processed.
	 * <p>
	 * This allows you to show some interaction in the gui.
	 */
	void onSearchEnd();

	/**
	 * Configure the widget with previously saved settings.
	 *
	 * @param settings settings
	 */
	void initialize(Criterion settings);

	/**
	 * This method allows you to manually start the search, it's like the user clicked te search button.
	 * (Handy in case you have/want to add multiple ways to start the search (for instance on doubleclick in a list))
	 */
	void startSearch();

	/**
	 * Clean up the widget to its initial state.
	 */
	void reset();

	/**
	 * Hide the search buttons.
	 */
	void hideSearchButtons();

	/**
	 * Show the search buttons.
	 */
	void showSearchButtons();

	// ----------------------------------------------------------

	/**
	 * Handler to be notified when the user presses the save button.
	 * 
	 * @author Kristof Heirwegh
	 */
	public interface SaveRequestHandler {
		void onSaveRequested(SaveRequestEvent event);
		void onCancelRequested(SaveRequestEvent event);
	}

	/**
	 * Handler to be notified when the user presses the search button.
	 * 
	 * @author Kristof Heirwegh
	 */
	public interface SearchRequestHandler {
		void onSearchRequested(SearchRequestEvent event);
		void onCancelRequested(SearchRequestEvent event);
	}

	/**
	 * Handler to be notified when the user presses the favourites button.
	 * 
	 * @author Kristof Heirwegh
	 */
	public interface FavouriteRequestHandler {
		void onAddRequested(FavouriteEvent event);
		void onDeleteRequested(FavouriteEvent event);
		void onChangeRequested(FavouriteEvent event);
	}

	/**
	 * Event used in {@link SearchWidget} handlers.
	 * 
	 * @author Kristof Heirwegh
	 */
	public static class SearchWidgetEvent {
		private final SearchWidget source;
		private final Criterion criterion;

		/**
		 * Create a {@link SearchWidgetEvent}.
		 *
		 * @param source source widget
		 * @param criterion criterion
		 */
		public SearchWidgetEvent(SearchWidget source, Criterion criterion) {
			this.source = source;
			this.criterion = criterion;
		}

		/**
		 * Get the source widget.
		 *
		 * @return source widget.
		 */
		public SearchWidget getSource() {
			return source;
		}

		/**
		 * Get the criterion.
		 *
		 * @return criterion
		 */
		public Criterion getCriterion() {
			return criterion;
		}
	}

	/**
	 * Event used in {@link SearchWidget} handlers.
	 * 
	 * @author Kristof Heirwegh
	 */
	public static class SaveRequestEvent extends SearchWidgetEvent {
		public SaveRequestEvent(SearchWidget source, Criterion criterion) {
			super(source, criterion);
		}
	}

	/**
	 * Event used in {@link SearchWidget} handlers.
	 * 
	 * @author Kristof Heirwegh
	 */
	public static class SearchRequestEvent extends SearchWidgetEvent {
		public SearchRequestEvent(SearchWidget source, Criterion criterion) {
			super(source, criterion);
		}
	}
}