org.eclipse.gef.AutoexposeHelper Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2000, 2010, 2012 IBM Corporation, Gerhardt Informatics Kft. 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
* Gerhardt Informatics Kft. - GEFGWT port
*******************************************************************************/
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
* DragTrackers 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.
*
* 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.
*
* 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 true 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 step(Point) at
* any time, even if false was never returned, such as when the
* user releases the mouse.
*
* @author hudsonr
*/
public interface AutoexposeHelper {
/**
* Returns true 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
* true, or it may wait for {@link #step(Point)} to be called
* later.
*
* @param where
* the mouse's current location in the viewer
* @return true 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 true, and the conditions
* are deemed appropriate to continue the autoexpose process.
*
* The client may stop calling this method at any time, even if the previous
* invocation returned true. 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;
}
}
}