/*******************************************************************************
 * 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.List;

import org.eclipse.core.runtime.IAdaptable;

import org.eclipse.gef.commands.Command;

/**
 * EditParts are the building blocks of GEF Viewers. As the <I>Controller</I>,
 * an EditPart ties the application's model to a visual representation.
 * EditParts are responsible for making changes to the model. EditParts
 * typically control a single model object or a coupled set of object. Visual
 * representations include {@link org.eclipse.draw2d.IFigure Figures} and
 * {@link org.eclipse.swt.widgets.TreeItem TreeItems}. Model objects are often
 * composed of other objects that the User will interact with. Similarly,
 * EditParts can be composed of or have references to other EditParts.
 * <P>
 * The creator of an EditPart should call only setModel(Object). The remaining
 * API is used mostly by Tools, EditPolicies, and other EditParts. CHANGES are
 * made to the model, not the EditPart.
 * <P>
 * Most interaction with EditParts is achieved using {@link Request Requests}. A
 * Request specifies the type of interaction. Requests are used in
 * {@link #getTargetEditPart(Request) targeting}, filtering the selection (using
 * {@link #understandsRequest(Request)}), graphical
 * {@link #showSourceFeedback(Request)} feedback, and most importantly,
 * {@link #getCommand(Request) obtaining} commands. Only {@link Command
 * Commands} should change the model.
 * <p>
 * IMPORTANT: This interface is <EM>not</EM> intended to be implemented by
 * clients. Clients should inherit from
 * {@link org.eclipse.gef.editparts.AbstractEditPart}. New methods may be added
 * in the future.
 */
public interface EditPart extends IAdaptable {

	/**
	 * Used to indicate no selection
	 */
	int SELECTED_NONE = 0;

	/**
	 * Used to indicate non-primary selection
	 */
	int SELECTED = 1;

	/**
	 * Used to indicate primary selection, or "Anchor" selection. Primary
	 * selection is defined as the last object selected.
	 */
	int SELECTED_PRIMARY = 2;

	/**
	 * Activates the EditPart. EditParts that observe a dynamic model or support
	 * editing must be <i>active</i>. Called by the managing EditPart, or the
	 * Viewer in the case of the {@link RootEditPart}. This method may be called
	 * again once {@link #deactivate()} has been called.
	 * <P>
	 * During activation the receiver should:
	 * <UL>
	 * <LI>begin to observe its model if appropriate, and should continue the
	 * observation until {@link #deactivate()} is called.
	 * <LI>activate all of its EditPolicies. EditPolicies may also observe the
	 * model, although this is rare. But it is common for EditPolicies to
	 * contribute additional visuals, such as selection handles or feedback
	 * during interactions. Therefore it is necessary to tell the EditPolicies
	 * when to start doing this, and when to stop.
	 * <LI>call activate() on the EditParts it manages. This includes its
	 * children, and for GraphicalEditParts, its <i>source connections</i>.
	 * </UL>
	 */
	void activate();

	/**
	 * Adds a listener to the EditPart. Duplicate calls result in duplicate
	 * notification.
	 * 
	 * @param listener
	 *            the Listener
	 */
	void addEditPartListener(EditPartListener listener);

	/**
	 * Called <em>after</em> the EditPart has been added to its parent. This is
	 * used to indicate to the EditPart that it should refresh itself for the
	 * first time.
	 */
	void addNotify();

	/**
	 * Deactivates the EditPart. EditParts that observe a dynamic model or
	 * support editing must be <i>active</i>. <code>deactivate()</code> is
	 * guaranteed to be called when an EditPart will no longer be used. Called
	 * by the managing EditPart, or the Viewer in the case of the
	 * {@link RootEditPart}. This method may be called multiple times.
	 * <P>
	 * During deactivation the receiver should:
	 * <UL>
	 * <LI>remove all listeners that were added in {@link #activate}
	 * <LI>deactivate all of its EditPolicies. EditPolicies may be contributing
	 * additional visuals, such as selection handles or feedback during
	 * interactions. Therefore it is necessary to tell the EditPolicies when to
	 * start doing this, and when to stop.
	 * <LI>call deactivate() on the EditParts it manages. This includes its
	 * children, and for <code>GraphicalEditParts</code>, its <i>source
	 * connections</i>.
	 * </UL>
	 */
	void deactivate();

	/**
	 * Erases <i>source</i> feedback for the specified {@link Request}. A
	 * Request is used to describe the type of source feedback that should be
	 * erased. This method should only be called once to erase feedback. It
	 * should only be called in conjunction with a prior call to
	 * {@link #showSourceFeedback(Request)}.
	 * 
	 * @param request
	 *            the type of feedback that is being erased
	 */
	void eraseSourceFeedback(Request request);

	/**
	 * Erases <i>target</i> feedback for the specified {@link Request}. A
	 * Request is used to describe the type of target feedback that should be
	 * erased. This method should only be called once to erase feedback. It
	 * should only be called in conjunction with a prior call to
	 * {@link #showTargetFeedback(Request)}.
	 * 
	 * @param request
	 *            the type of feedback that is being erased
	 */
	void eraseTargetFeedback(Request request);

	/**
	 * Returns the List of children <code>EditParts</code>. This method should
	 * rarely be called, and is only made public so that helper objects of this
	 * EditPart, such as EditPolicies, can obtain the children. The returned
	 * List may be by reference, and should never be modified.
	 * 
	 * @return a <code>List</code> of children
	 */
	List getChildren();

	/**
	 * Returns the {@link Command} to perform the specified Request or
	 * <code>null</code>.
	 * 
	 * @param request
	 *            describes the Command being requested
	 * @return <code>null</code> or a Command
	 */
	Command getCommand(Request request);

	/**
	 * Returns a {@link DragTracker} for dragging this EditPart. The
	 * {@link org.eclipse.gef.tools.SelectionTool SelectionTool} is the only
	 * Tool by default that calls this method. The SelectionTool will use a
	 * {@link org.eclipse.gef.requests.SelectionRequest} to provide information
	 * such as which mouse button is down, and what modifier keys are pressed.
	 * 
	 * @param request
	 *            a <code>Request</code> indicating the context of the drag
	 * @return <code>null</code> or a DragTracker
	 */
	DragTracker getDragTracker(Request request);

	/**
	 * @param key
	 *            the key identifying the EditPolicy
	 * @return <code>null</code> or the EditPolicy installed with the given key
	 */
	EditPolicy getEditPolicy(Object key);

	/**
	 * Returns the primary model object that this EditPart represents. EditParts
	 * may correspond to more than one model object, or even no model object. In
	 * practice, the Object returned is used by other EditParts to identify this
	 * EditPart. In addition, EditPolicies probably rely on this method to build
	 * Commands that operate on the model.
	 * 
	 * @return <code>null</code> or the primary model object
	 */
	Object getModel();

	/**
	 * Returns the parent <code>EditPart</code>. This method should only be
	 * called internally or by helpers such as EditPolicies.
	 * 
	 * @return <code>null</code> or the parent {@link EditPart}
	 */
	EditPart getParent();

	/**
	 * Returns the {@link RootEditPart}. This method should only be called
	 * internally or by helpers such as edit policies. The root can be used to
	 * get the viewer.
	 * 
	 * @return <code>null</code> or the {@link RootEditPart}
	 */
	RootEditPart getRoot();

	/**
	 * Returns the selected state of this EditPart. This method should only be
	 * called internally or by helpers such as EditPolicies.
	 * 
	 * @return one of:
	 *         <UL>
	 *         <LI> {@link #SELECTED}
	 *         <LI> {@link #SELECTED_NONE}
	 *         <LI> {@link #SELECTED_PRIMARY}
	 *         </UL>
	 */
	int getSelected();

	/**
	 * Return the <code>EditPart</code> that should be used as the <i>target</i>
	 * for the specified <code>Request</code>. Tools will generally call this
	 * method with the mouse location so that the receiver can implement drop
	 * targeting. Typically, if this EditPart is not the requested target (for
	 * example, this EditPart is not a composite), it will forward the call to
	 * its parent.
	 * 
	 * @param request
	 *            the type of target being requested
	 * @return <code>null</code> or the target
	 */
	EditPart getTargetEditPart(Request request);

	/**
	 * Convenience method for returning the <code>EditPartViewer</code> for this
	 * part.
	 * 
	 * @return the {@link EditPartViewer} or <code>null</code>
	 */
	EditPartViewer getViewer();

	/**
	 * Returns true if this EditPart has <i>focus</i>. The focus EditPart is a
	 * property of the EditPartViewer. The Viewer keeps this property in sync
	 * with its focus.
	 * 
	 * @see EditPartViewer#getFocusEditPart()
	 * @return true if the EditPart has focus
	 */
	boolean hasFocus();

	/**
	 * Installs an EditPolicy for a specified <i>role</i>. A <i>role</i> is is
	 * simply an Object used to identify the EditPolicy. An example of a role is
	 * layout. {@link EditPolicy#LAYOUT_ROLE} is generally used as the key for
	 * this EditPolicy. <code>null</code> is a valid value for reserving a
	 * location.
	 * 
	 * @param role
	 *            an identifier used to key the EditPolicy
	 * @param editPolicy
	 *            the EditPolicy
	 */
	void installEditPolicy(Object role, EditPolicy editPolicy);

	/**
	 * returns <code>true</code> if the EditPart is active. Editparts are active
	 * after {@link #activate()} is called, and until {@link #deactivate()} is
	 * called.
	 * 
	 * @return <code>true</code> when active
	 */
	boolean isActive();

	/**
	 * Returns <code>true</code> if the EditPart is selectable. A selectable
	 * EditPart may be selected as a result of the
	 * {@link org.eclipse.gef.tools.SelectionTool} receiving a mouse down, or as
	 * a result of the User pressing a key to change selection.
	 * 
	 * @return <code>true</code> if the receiver can be selected
	 */
	boolean isSelectable();

	/**
	 * Performs the specified Request. This method can be used to send a generic
	 * message to an EditPart. If the EditPart interprets this request to mean
	 * make a change in the model, it should still use <code>Commands</code> and
	 * the <code>CommandStack</code> so that the change is undoable. The
	 * CommandStack is available from the <code>EditDomain</code>.
	 * 
	 * @param request
	 *            the request to be performed
	 */
	void performRequest(Request request);

	/**
	 * Called to force a refresh of this EditPart. All visuals properties will
	 * be updated, as well as structural features like children.
	 */
	void refresh();

	/**
	 * Removes the first occurance of the specified listener from the list of
	 * listeners. Does nothing if the listener was not present.
	 * 
	 * @param listener
	 *            the listener being removed
	 */
	void removeEditPartListener(EditPartListener listener);

	/**
	 * Removes the EditPolicy for the given <i>role</i>. The EditPolicy is
	 * deactivated if it is active. The position for that role is maintained
	 * with <code>null</code> in the place of the old EditPolicy.
	 * 
	 * @param role
	 *            the key identifying the EditPolicy to be removed
	 * @see #installEditPolicy(Object, EditPolicy)
	 */
	void removeEditPolicy(Object role);

	/**
	 * Called when the EditPart is being permanently removed from its
	 * {@link EditPartViewer}. This indicates that the EditPart will no longer
	 * be in the Viewer, and therefore should remove itself from the Viewer.
	 * This method is <EM>not</EM> called when a Viewer is disposed. It is only
	 * called when the EditPart is removed from its parent. This method is the
	 * inverse of {@link #addNotify()}
	 */
	void removeNotify();

	/**
	 * Set the <i>focus</i> property to reflect the value in the EditPartViewer.
	 * Focus is determined by the EditPartViewer.
	 * <P>
	 * <I>Focus</I> is considered to be part of the selected state, changing
	 * this value will fire
	 * {@link EditPartListener#selectedStateChanged(EditPart)}.
	 * <P>
	 * IMPORTANT: This method should only be called by the EditPartViewer.
	 * 
	 * @param hasFocus
	 *            boolean indicating if this part has focus
	 */
	void setFocus(boolean hasFocus);

	/**
	 * <img src="doc-files/dblack.gif"/>Sets the model. This method is made
	 * public to facilitate the use of {@link EditPartFactory EditPartFactories}
	 * .
	 * 
	 * <P>
	 * IMPORTANT: This method should only be called once.
	 * 
	 * @param model
	 *            the Model
	 */
	void setModel(Object model);

	/**
	 * <img src="doc-files/dblack.gif"/>Sets the parent. This should only be
	 * called by the parent EditPart.
	 * 
	 * @param parent
	 *            the parent EditPart
	 */
	void setParent(EditPart parent);

	/**
	 * <img src="doc-files/dblack.gif"/> Sets the selected state property to
	 * reflect the selection in the EditPartViewer. Fires
	 * selectedStateChanged(EditPart) to any EditPartListeners. Selection is
	 * maintained by the EditPartViewer.
	 * <P>
	 * IMPORTANT: This method should only be called by the EditPartViewer.
	 * 
	 * @param value
	 *            an enum indicating the selected state
	 * @see #getSelected()
	 */
	void setSelected(int value);

	/**
	 * Shows or updates source feedback for the given request. This method may
	 * be called multiple times so that the feedback can be updated for changes
	 * in the request, such as the mouse location changing.
	 * 
	 * @param request
	 *            request describing the type of feedback
	 */
	void showSourceFeedback(Request request);

	/**
	 * Shows or updates target feedback for the given request. This method can
	 * be called multiple times so that the feedback can be updated for changes
	 * in the request, such as the mouse location changing.
	 * 
	 * @param request
	 *            request describing the type of feedback
	 */
	void showTargetFeedback(Request request);

	/**
	 * Used to filter EditParts out of the current <i>selection</i>. If an
	 * operation is going to be performed on the current selection, the
	 * selection can first be culled to remove EditParts that do not participate
	 * in the operation. For example, when aligning the left edges of
	 * GraphicalEditParts, it makes sense to ignore any selected
	 * ConnectionEditParts, as they cannot be aligned.
	 * 
	 * @param request
	 *            a <code>Request</code> describing an operation of some type
	 * @return <code>true</code> if Request is understood
	 */
	boolean understandsRequest(Request request);

}