IAnchor.java

/*******************************************************************************
 * Copyright (c) 2014, 2016 itemis AG 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:
 *     Alexander Nyßen (itemis AG)  - initial API and implementation
 *     Matthias Wienand (itemis AG) - initial API and implementation
 *
 *******************************************************************************/
package org.eclipse.gef.fx.anchors;

import org.eclipse.gef.geometry.planar.Point;

import javafx.beans.property.ReadOnlyMapProperty;
import javafx.beans.property.ReadOnlyObjectProperty;
import javafx.collections.ObservableMap;
import javafx.scene.Node;

/**
 * An {@link IAnchor} is a visual anchor that will provide positions for
 * attached {@link AnchorKey}s (i.e. anchored {@link Node}s) in local
 * coordinates of the {@link AnchorKey}'s anchored {@link Node}.
 * <p>
 * The position for each attached {@link Node} will be recomputed in case the
 * attached {@link Node} or any of its ancestors are changed in a way that has
 * an effect on the position being provided for the attached {@link Node}. The
 * {@link #positionsUnmodifiableProperty()} will be updated accordingly, it may
 * be monitored for changes.
 * <p>
 * An {@link IAnchor} may be bound to an anchorage {@link Node}. If this is the
 * case, positions for all attached {@link Node}s will also be recomputed in
 * case the anchorage {@link Node} or any of its ancestors are changed in a way
 * that will have an effect on the position of the attached {@link Node}.
 *
 * @author anyssen
 * @author mwienand
 */
public interface IAnchor {

	/**
	 * Provides a read-only property with the anchorage {@link Node} this
	 * {@link IAnchor} is bound to. The property value may be <code>null</code>
	 * in case this {@link IAnchor} is not bound to an anchorage {@link Node}.
	 *
	 * @return A read-only property storing the anchorage {@link Node}.
	 */
	ReadOnlyObjectProperty<Node> anchorageProperty();

	/**
	 * Attaches the given {@link AnchorKey} to this {@link IAnchor}.
	 *
	 * @param key
	 *            The {@link AnchorKey} to be attached.
	 */
	void attach(AnchorKey key);

	/**
	 * Detaches the given {@link AnchorKey} from this {@link IAnchor}.
	 *
	 * @param key
	 *            The {@link AnchorKey} to be detached.
	 */
	void detach(AnchorKey key);

	/**
	 * Provides the anchorage {@link Node} this {@link IAnchor} is bound to.
	 * Will return the value of the {@link #anchorageProperty()}.
	 *
	 * @return The value of the {@link #anchorageProperty()}.
	 */
	Node getAnchorage();

	/**
	 * Provides a position for the given {@link AnchorKey}. The provided
	 * {@link AnchorKey} has to be attached to this {@link IAnchor} (see
	 * {@link #attach(AnchorKey)}).
	 *
	 * @param key
	 *            The {@link AnchorKey} to retrieve a position for. It has to be
	 *            attached ({@link #attach(AnchorKey)}) to this {@link IAnchor}
	 *            before.
	 * @return The position for the given {@link AnchorKey} within local
	 *         coordinates of the {@link AnchorKey}'s anchored {@link Node}.
	 */
	Point getPosition(AnchorKey key);

	/**
	 * Provides an observable read-only (map) with positions (in local
	 * coordinates of the anchored {@link Node}s) for all attached
	 * {@link AnchorKey}s. The positions will be updated for all attached
	 * {@link AnchorKey}s if the attached {@link Node}s or the anchorage
	 * {@link Node}, the {@link IAnchor} is bound to, or any of their ancestors
	 * changes in a way that will effect the positions (within the local
	 * coordinate space of the attached {@link Node}s).
	 *
	 * @return A read-only observable map storing positions for all attached
	 *         {@link AnchorKey}s.
	 */
	public ObservableMap<AnchorKey, Point> getPositionsUnmodifiable();

	/**
	 * Determines if the given {@link AnchorKey} is currently attached to this
	 * {@link IAnchor}.
	 *
	 * @param key
	 *            The {@link AnchorKey} to test.
	 * @return <code>true</code> if the given key is attached, otherwise
	 *         <code>false</code>.
	 */
	boolean isAttached(AnchorKey key);

	/**
	 * Provides a read-only (map) property with positions (in local coordinates
	 * of the anchored {@link Node}s) for all attached {@link AnchorKey}s. The
	 * positions will be updated for all attached {@link AnchorKey}s if the
	 * attached {@link Node}s or the anchorage {@link Node}, the {@link IAnchor}
	 * is bound to, or any of their ancestors changes in a way that will effect
	 * the positions (within the local coordinate space of the attached
	 * {@link Node}s).
	 *
	 * @return A read-only (map) property storing positions for all attached
	 *         {@link AnchorKey}s.
	 */
	public ReadOnlyMapProperty<AnchorKey, Point> positionsUnmodifiableProperty();

}