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