/*******************************************************************************
 * Copyright (c) 2003, 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 org.eclipse.draw2d.IFigure;
import org.eclipse.draw2d.PositionConstants;
import org.eclipse.draw2d.geometry.PrecisionPoint;
import org.eclipse.draw2d.geometry.PrecisionRectangle;
import org.eclipse.draw2d.geometry.Translatable;

/**
 * A helper used temporarily by Tools for snapping certain mouse interactions.
 * SnapToHelpers should not be reused by tools or by the editparts which provide
 * them to the tools. For example, for a move operation, the life-cycle of a
 * SnapToHelper begins when a drag is initiated, and ends when the drag is over.
 * If another drag is initiated right after the first one is completed, new
 * SnapToHelpers are employed. This means that helpers can assume that
 * everything else is static, and there is no need to track changes outside of
 * the helper.
 * 
 * @since 3.0
 * @author Randy Hudson
 * @author Pratik Shah
 */
public abstract class SnapToHelper implements PositionConstants {

	/**
	 * Translates from a given figure to absolute coordinates.
	 * 
	 * @param figure
	 *            the reference figure
	 * @param t
	 *            the object to translate
	 */
	protected void makeAbsolute(IFigure figure, Translatable t) {
		figure.translateToAbsolute(t);
	}

	/**
	 * Translates from absolute to coordinates relative to the given figure.
	 * 
	 * @param figure
	 *            the reference figure
	 * @param t
	 *            the object to translate
	 */
	protected void makeRelative(IFigure figure, Translatable t) {
		figure.translateToRelative(t);
	}

	/**
	 * Applies a snapping correction to the given result. Snapping can occur in
	 * the four primary directions: NORTH, SOUTH, EAST, WEST, as defined on
	 * {@link PositionConstants}. By default a Point is treated as an empty
	 * Rectangle. Only NORTH and WEST should be used in general. But SOUTH and
	 * EAST may also be used. Similarly, VERTICAL and HORIZONTAL may be used to
	 * allow a point to snap to the "center" or "middle" as defined by the
	 * concrete subclass.
	 * <P>
	 * The returned value should be a subset of the given snapDirections based
	 * on what correction was applied to the result. e.g., if the <b>x</b> value
	 * was adjusted, the returned value should not contain WEST, EAST, or
	 * HORIZONTAL.
	 * <P>
	 * All coordinate information received and returned by this method should be
	 * in absolute coordinates.
	 * 
	 * @param request
	 *            a request or <code>null</code>
	 * @param snapDirections
	 *            the directions in which snapping should occur.
	 * @param where
	 *            the rectangle used to determine snapping
	 * @param result
	 *            the result
	 * @return the remaining snap locations
	 */
	public int snapPoint(Request request, int snapDirections,
			PrecisionPoint where, PrecisionPoint result) {
		PrecisionRectangle rect = new PrecisionRectangle();
		PrecisionRectangle resultRect = new PrecisionRectangle();
		rect.setPreciseX(where.preciseX());
		rect.setPreciseY(where.preciseY());
		snapDirections = snapRectangle(request, snapDirections, rect,
				resultRect);
		result.setPreciseX(result.preciseX() + resultRect.preciseX());
		result.setPreciseY(result.preciseY() + resultRect.preciseY());
		return snapDirections;
	}

	/**
	 * A convenience method for snapping a Point based on an array of
	 * rectangles. By default, this method will construct an empty rectangle at
	 * the same locations as the provided point, and call
	 * {@link #snapRectangle(Request, int, PrecisionRectangle[], PrecisionRectangle)}
	 * . The intended usage of this method is when dragging one or more parts in
	 * a diagram.
	 * <P>
	 * The returned value should be a subset of the given snapDirections based
	 * on what correction was applied to the result. e.g., if the <b>x</b> value
	 * was adjusted, the returned value should not contain WEST, EAST, or
	 * HORIZONTAL.
	 * <P>
	 * All coordinate information received and returned by this method should be
	 * in absolute coordinates.
	 * 
	 * @param request
	 *            the request or <code>null</code>
	 * @param snapLocations
	 *            the types of snapping to perform
	 * @param rects
	 *            an array of one or more rectangles used to perform the
	 *            snapping
	 * @param result
	 *            the correction will be applied to this point
	 * @return the remaining snap locations
	 */
	public int snapPoint(Request request, int snapLocations,
			PrecisionRectangle rects[], PrecisionPoint result) {
		PrecisionRectangle resultRect = new PrecisionRectangle();
		snapLocations = snapRectangle(request, snapLocations, rects, resultRect);
		result.setPreciseX(result.preciseX() + resultRect.preciseX());
		result.setPreciseY(result.preciseY() + resultRect.preciseY());
		return snapLocations;
	}

	/**
	 * A convenience method for snapping a Rectangle based on one or more
	 * rectangles. This method will call
	 * {@link #snapRectangle(Request, int, PrecisionRectangle, PrecisionRectangle)}
	 * for each rectangle in the array or until no more snap locations remain.
	 * <P>
	 * All coordinate information received and returned by this method should be
	 * in absolute coordinates.
	 * 
	 * @param request
	 *            the request or <code>null</code>
	 * @param baseRects
	 *            the prioritized rectangles to snap to
	 * @param result
	 *            the output
	 * @param snapOrientation
	 *            the input snap locations
	 * @return the remaining snap locations
	 */
	public int snapRectangle(Request request, int snapOrientation,
			PrecisionRectangle baseRects[], PrecisionRectangle result) {

		for (int i = 0; i < baseRects.length && snapOrientation != 0; i++)
			snapOrientation = snapRectangle(request, snapOrientation,
					baseRects[i], result);

		return snapOrientation;
	}

	/**
	 * Applies a snap correction to a Rectangle based on a given Rectangle. The
	 * provided baseRect will be used as a reference for snapping. The types of
	 * snapping to be performed are indicated by the snapOrientation parameter.
	 * The correction is applied to the result field.
	 * <P>
	 * The baseRect is not modified. The correction is applied to the result.
	 * The request's {@link Request#getExtendedData() extended data} may contain
	 * additional information about the snapping which was performed.
	 * <P>
	 * All coordinate information received and returned by this method should be
	 * in absolute coordinates.
	 * 
	 * @since 3.0
	 * @param request
	 *            the request or <code>null</code>
	 * @param baseRect
	 *            the input rectangle
	 * @param result
	 *            the correction is applied to this rectangle
	 * @param snapOrientation
	 *            the input snap locations
	 * @return the remaining snap locations
	 */
	public abstract int snapRectangle(Request request, int snapOrientation,
			PrecisionRectangle baseRect, PrecisionRectangle result);

}