/*******************************************************************************
 * Copyright (c) 2000, 2010 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.gef;

import java.util.Collection;

import org.eclipse.draw2d.geometry.Point;

/**
 * A helper returned from a {@link org.eclipse.gef.GraphicalEditPart}. Certain
 * <code>DragTrackers</code> tools and native drop listeners will make use of
 * autoexpose helpers to reveal any potential drop areas that are currently not
 * visible to the user. An example of this is scrolling a container to reveal
 * unexposed area. Another example is a bunch of stacked containers in a
 * "tab folder" arrangement, whever hovering over a tab should switch which
 * container is on top.
 * <P>
 * Autoexpose helpers are obtained from editparts that are target of whatever
 * operation is being performed. If the target provides no helper, its parent
 * chain is traversed looking for helpers. A helper will be obtained under
 * conditions deemed appropriate by the caller, such as when the mouse has
 * paused for some amount of time in the current location.
 * <P>
 * An autoexpose helper may be short-lived or long-running. A short-lived helper
 * would be something like the example described above when a "page" is being
 * flipped. A long-running example is auto-scrolling. A helper requests to
 * remains active by returning <code>true</code> from its {@link #step(Point)}
 * method for as long as necessary. An active helper can remain active even as
 * the mouse is moving. The client may stop calling <code>step(Point)</code> at
 * any time, even if <code>false</code> was never returned, such as when the
 * user releases the mouse.
 * 
 * @author hudsonr
 */
public interface AutoexposeHelper {

	/**
	 * Returns <code>true</code> if the specified location is interesting to the
	 * helper. This method gets called as part of the search for an
	 * AutoexposeHelper. The helper should do something if it returns
	 * <code>true</code>, or it may wait for {@link #step(Point)} to be called
	 * later.
	 * 
	 * @param where
	 *            the mouse's current location in the viewer
	 * @return <code>true</code> if the location is interesting
	 */
	boolean detect(Point where);

	/**
	 * Performs the autoexpose and returns a hint indicating that the helper
	 * would like to remain active. The client will continue to call step() for
	 * as long as it previously returned <code>true</code>, and the conditions
	 * are deemed appropriate to continue the autoexpose process.
	 * <P>
	 * The client may stop calling this method at any time, even if the previous
	 * invocation returned <code>true</code>. The return value is a hint.
	 * 
	 * @param where
	 *            the current location of the mouse in the viewer
	 * @return a hint indicating whether this helper should continue to be
	 *         invoked
	 */
	boolean step(Point where);

	/**
	 * Used with EditPartViewers to find the AutoexposeHelper at a Point.
	 * Clients can instantiate the search, call
	 * {@link EditPartViewer#findObjectAtExcluding(Point,Collection, EditPartViewer.Conditional)}
	 * , and then check the {@link #result} field.
	 */
	class Search implements EditPartViewer.Conditional {
		/**
		 * Constructs a new Search at a point on the viewer.
		 * 
		 * @param pt
		 *            the mouse location
		 */
		public Search(Point pt) {
			where = pt;
		}

		/**
		 * the result of the search.
		 */
		private Point where;
		public AutoexposeHelper result;

		public boolean evaluate(EditPart editpart) {
			result = (AutoexposeHelper) editpart
					.getAdapter(AutoexposeHelper.class);
			if (result != null && result.detect(where))
				return true;
			result = null;
			return false;
		}
	}

}