| /******************************************************************************* |
| * 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.beans.PropertyChangeListener; |
| import java.util.Collection; |
| import java.util.List; |
| import java.util.Map; |
| |
| import org.eclipse.swt.graphics.Cursor; |
| import org.eclipse.swt.widgets.Composite; |
| import org.eclipse.swt.widgets.Control; |
| |
| import org.eclipse.jface.action.MenuManager; |
| import org.eclipse.jface.resource.JFaceResources; |
| import org.eclipse.jface.resource.ResourceManager; |
| import org.eclipse.jface.util.TransferDragSourceListener; |
| import org.eclipse.jface.util.TransferDropTargetListener; |
| import org.eclipse.jface.viewers.ISelection; |
| |
| import org.eclipse.draw2d.geometry.Point; |
| |
| /** |
| * An adapter on an SWT {@link org.eclipse.swt.widgets.Control} that manages the |
| * {@link org.eclipse.gef.EditPart EditParts}. The viewer is responsible for the |
| * editpart lifecycle. Editparts have <i>visuals</i>, such as |
| * <code>TreeItems</code> or <code>Figures</code>, which are hosted by the |
| * viewer and its control. The viewer provides targeting of editparts via their |
| * visuals. |
| * |
| * <P> |
| * A viewer is a {@link org.eclipse.jface.viewers.ISelectionProvider}. It |
| * maintains a list of selected editparts. The last member of this list is the |
| * <i>primary</i> member of the selection. The list should never be empty; when |
| * no editparts are selected, the viewer's contents editpart is used. |
| * |
| * <P> |
| * A viewer is populated by setting its <i>contents</i>. This can be done by |
| * passing the model corresponding to the contents. The viewer's |
| * {@link org.eclipse.gef.EditPartFactory EditPartFactory} is then used to |
| * create the contents editpart, and add it to the <i>root</i> editpart. |
| * Alternatively, the contents editpart itself can be provided. Once the |
| * contents editpart is parented, it will populate the rest of the viewer by |
| * calling its {@link EditPart#refresh()} method. |
| * |
| * <P> |
| * The Root editpart does not correspond to anything in the model, it is used to |
| * bootstrap the viewer, and to parent the contents. Depending on the type of |
| * viewer being used, it may be common to replace the root editpart. See |
| * implementations of {@link org.eclipse.gef.RootEditPart}. |
| * |
| * <P> |
| * An editpart's lifecycle is managed by the viewer. When the Viewer is |
| * realized, meaning it has an SWT <code>Control</code>, it activates its root, |
| * which in turn activates all editparts. Editparts are deactivated when they |
| * are removed from the viewer. When the viewer's control is disposed, all |
| * editparts are similarly deactivated by decativating the root. |
| * |
| * <P> |
| * A Viewer has an arbitrary collection of keyed properties that can be set and |
| * queried. A value of <code>null</code> is used to remove a key from the |
| * property map. A viewer will fire property change notification whenever these |
| * values are updated. |
| * |
| * <P> |
| * WARNING: This interface is not intended to be implemented. Clients should |
| * extend {@link org.eclipse.gef.ui.parts.AbstractEditPartViewer}. |
| */ |
| public interface EditPartViewer extends |
| org.eclipse.jface.viewers.ISelectionProvider { |
| |
| /** |
| * An object which evaluates an EditPart for an arbitrary property. |
| * Conditionals are used when querying a viewer for an editpart. |
| * |
| * @author hudsonr |
| */ |
| interface Conditional { |
| /** |
| * Returns <code>true</code> if the editpart meets this condition. |
| * |
| * @param editpart |
| * the editpart being evaluated |
| * @return <code>true</code> if the editpart meets the condition |
| */ |
| boolean evaluate(EditPart editpart); |
| } |
| |
| /** |
| * Provided for compatibility with existing code. |
| * |
| * @param listener |
| * a drag source listener |
| * @see #addDragSourceListener(TransferDragSourceListener) |
| */ |
| void addDragSourceListener( |
| org.eclipse.gef.dnd.TransferDragSourceListener listener); |
| |
| /** |
| * Adds a <code>TransferDragSourceListener</code> to this viewer. This has |
| * the side-effect of creating a {@link org.eclipse.swt.dnd.DragSource} on |
| * the viewer's Control. A Control can only have a single DragSource. |
| * Clients must not create their own DragSource when using this method. |
| * |
| * @param listener |
| * the listener |
| */ |
| void addDragSourceListener(TransferDragSourceListener listener); |
| |
| /** |
| * Provided for compatibility with existing code. |
| * |
| * @param listener |
| * the listener |
| * @see #addDropTargetListener(TransferDropTargetListener) |
| */ |
| void addDropTargetListener( |
| org.eclipse.gef.dnd.TransferDropTargetListener listener); |
| |
| /** |
| * Adds a <code>TransferDropTargetListener</code> to this viewer. This has |
| * the side-effect of creating a {@link org.eclipse.swt.dnd.DropTarget} on |
| * the viewer's Control. A Control can only have a single DropTarget. |
| * Clients must not create their own DropTarget when using this method. |
| * |
| * @param listener |
| * the listener |
| */ |
| void addDropTargetListener(TransferDropTargetListener listener); |
| |
| /** |
| * Adds a listener to be notified of viewer property changes. |
| * |
| * @param listener |
| * the listener |
| */ |
| void addPropertyChangeListener(PropertyChangeListener listener); |
| |
| /** |
| * Appends the specified <code>EditPart</code> to the viewer's |
| * <i>selection</i>. The EditPart becomes the new primary selection. Fires |
| * selection changed to all |
| * {@link org.eclipse.jface.viewers.ISelectionChangedListener}s. |
| * |
| * @param editpart |
| * the EditPart to append |
| */ |
| void appendSelection(EditPart editpart); |
| |
| /** |
| * Optionally creates the default {@link org.eclipse.swt.widgets.Control |
| * Control} using the default style. The Control can also be created |
| * externally and then set into the Viewer. |
| * |
| * @param composite |
| * the parent in which create the SWT <code>Control</code> |
| * @see #setControl(Control) |
| * @return the created Control for convenience |
| */ |
| Control createControl(Composite composite); |
| |
| /** |
| * Removes the specified <code>EditPart</code> from the current selection. |
| * If the selection becomes empty, the viewer's {@link #getContents() |
| * contents} becomes the current selected part. The last EditPart in the new |
| * selection is made {@link EditPart#SELECTED_PRIMARY primary}. |
| * <P> |
| * Fires selection changed to |
| * {@link org.eclipse.jface.viewers.ISelectionChangedListener}s. |
| * |
| * @param editpart |
| * the <code>EditPart</code> to deselect |
| */ |
| void deselect(EditPart editpart); |
| |
| /** |
| * Deselects all EditParts. The viewer's {@link #getContents() contents} |
| * becomes the current selection. Fires selection changed to |
| * {@link org.eclipse.jface.viewers.ISelectionChangedListener}s. |
| */ |
| void deselectAll(); |
| |
| /** |
| * Returns <code>null</code> or the <code>EditPart</code> associated with |
| * the specified location. The location is relative to the client area of |
| * the Viewer's <code>Control</code>. An EditPart is not directly visible. |
| * It is targeted using its <i>visual part</i> which it registered using the |
| * {@link #getVisualPartMap() visual part map}. What constitutes a <i>visual |
| * part</i> is viewer-specific. Examples include Figures and TreeItems. |
| * |
| * @param location |
| * The location |
| * @return <code>null</code> or an EditPart |
| */ |
| EditPart findObjectAt(Point location); |
| |
| /** |
| * Returns <code>null</code> or the <code>EditPart</code> at the specified |
| * location, excluding the specified set. This method behaves similarly to |
| * {@link #findObjectAt(Point)}. |
| * |
| * @param location |
| * The mouse location |
| * @param exclusionSet |
| * The set of EditParts to be excluded |
| * @return <code>null</code> or an EditPart |
| */ |
| EditPart findObjectAtExcluding(Point location, Collection exclusionSet); |
| |
| /** |
| * Returns <code>null</code> or the <code>EditPart</code> at the specified |
| * location, using the given exclusion set and conditional. This method |
| * behaves similarly to {@link #findObjectAt(Point)}. |
| * |
| * @param location |
| * The mouse location |
| * @param exclusionSet |
| * The set of EditParts to be excluded |
| * @param conditional |
| * the Conditional used to evaluate a potential hit |
| * @return <code>null</code> or an EditPart |
| */ |
| EditPart findObjectAtExcluding(Point location, Collection exclusionSet, |
| Conditional conditional); |
| |
| /** |
| * Flushes all pending updates to the Viewer. |
| */ |
| void flush(); |
| |
| /** |
| * Returns the <i>contents</i> of this Viewer. The contents is the EditPart |
| * associated with the top-level model object. It is considered to be |
| * "The Diagram". If the user has nothing selected, the <i>contents</i> is |
| * implicitly the selected object. |
| * <P> |
| * The <i>Root</i> of the Viewer is different. By constrast, the root is |
| * never selected or targeted, and does not correspond to something in the |
| * model. |
| * |
| * @see #getRootEditPart() |
| * @return the <i>contents</i> <code>EditPart</code> |
| */ |
| EditPart getContents(); |
| |
| /** |
| * Returns <code>null</code> or the MenuManager for this viewer. The menu |
| * manager is set using {@link #setContextMenu(MenuManager)}. |
| * |
| * @return <code>null</code> or a MenuManager |
| */ |
| MenuManager getContextMenu(); |
| |
| /** |
| * Returns <code>null</code> or the SWT <code>Control</code> for this |
| * viewer. The control is either set explicitly or can be created by the |
| * viewer. |
| * |
| * @see #setControl(Control) |
| * @see #createControl(Composite) |
| * @return the SWT <code>Control</code> |
| */ |
| Control getControl(); |
| |
| /** |
| * Returns the {@link EditDomain EditDomain} to which this viewer belongs. |
| * |
| * @return the viewer's EditDomain |
| */ |
| EditDomain getEditDomain(); |
| |
| /** |
| * Returns the <code>EditPartFactory</code> for this viewer. The |
| * EditPartFactory is used to create the <i>contents</i> EditPart when |
| * {@link #setContents(Object)} is called. It is made available so that |
| * other EditParts can use it to create their children or connection |
| * editparts. |
| * |
| * @return EditPartFactory |
| */ |
| EditPartFactory getEditPartFactory(); |
| |
| /** |
| * Returns the {@link Map} for registering <code>EditParts</code> by |
| * <i>Keys</i>. EditParts may register themselves using any method, and may |
| * register themselves with multiple keys. The purpose of such registration |
| * is to allow an EditPart to be found by other EditParts, or by listeners |
| * of domain notifiers. By default, EditParts are registered by their model. |
| * <P> |
| * Some models use a "domain" notification system, in which all changes are |
| * dispatched to a single listener. Such a listener might use this map to |
| * lookup editparts for a given model, and then ask the editpart to update. |
| * |
| * @return the registry map |
| */ |
| Map getEditPartRegistry(); |
| |
| /** |
| * Returns the <i>focus</i> <code>EditPart</code>. Focus refers to keyboard |
| * focus. This is the same concept as focus in a native Tree or Table. The |
| * User can change focus using the keyboard without affecting the currently |
| * selected objects. Never returns <code>null</code>. |
| * |
| * @return the <i>focus</i> <code>EditPart</code> |
| */ |
| EditPart getFocusEditPart(); |
| |
| /** |
| * Returns the <code>KeyHandler</code> for this viewer. The KeyHandler is |
| * sent KeyEvents by the currently active <code>Tool</code>. This is |
| * important, because only the current tool knows if it is in a state in |
| * which keys should be ignored, such as during a drag. By default, only the |
| * {@link org.eclipse.gef.tools.SelectionTool} forwards keysrokes. It does |
| * not do so during a drag. |
| * |
| * @return <code>null</code> or a KeyHandler |
| */ |
| KeyHandler getKeyHandler(); |
| |
| /** |
| * Returns the value of the given property. Returns <code>null</code> if the |
| * property has not been set, or has been set to null. |
| * |
| * @param key |
| * the property's key |
| * @return the given properties value or <code>null</code>. |
| */ |
| Object getProperty(String key); |
| |
| /** |
| * Returns <code>null</code>, or the ResourceManager for this Viewer. Once a |
| * viewer has a Control, clients may access the viewer's resource manager. |
| * Any resources constructed using this manager, but not freed, will be |
| * freed when the viewer's control is disposed. This does not mean that |
| * clients should be lazy about deallocating resources. If a resource is no |
| * longer needed but the viewer is still in use, the client must deallocate |
| * the resource. |
| * <P> |
| * Typical usage is by EditParts contained inside the viewer. EditParts |
| * which are removed from the viewer should free their resources during |
| * {@link EditPart#removeNotify()}. When the viewer is disposed, |
| * <code>removeNotify()</code> is not called, but the viewer's resource |
| * manager will be disposed anyway. |
| * <P> |
| * The viewer's default resource manager is linked to JFace's |
| * {@link JFaceResources#getResources() global shared resources}. |
| * |
| * @return the ResourceManager associated with this viewer |
| * @since 3.3 |
| */ |
| ResourceManager getResourceManager(); |
| |
| /** |
| * Returns the <code>RootEditPart</code>. The RootEditPart is a special |
| * EditPart that serves as the parent to the contents editpart. The |
| * <i>root</i> is never selected. The root does not correspond to anything |
| * in the model. The User does not interact with the root. |
| * <P> |
| * The RootEditPart has a single child: the {@link #getContents() contents}. |
| * <P> |
| * By defining the concept of "root", GEF allows the application's "real" |
| * EditParts to be more homogeneous. For example, all non-root EditParts |
| * have a parent. Also, it allows applications to change the type of root |
| * being used without affecting their own editpart implementation hierarchy. |
| * |
| * @see #getContents() |
| * @see #setRootEditPart(RootEditPart) |
| * @return the RootEditPart |
| */ |
| RootEditPart getRootEditPart(); |
| |
| /** |
| * Returns an unmodifiable <code>List</code> containing zero or more |
| * selected editparts. This list may be empty. In contrast, the inherited |
| * method |
| * {@link org.eclipse.jface.viewers.ISelectionProvider#getSelection()} |
| * should not return an empty selection. When no editparts are selected, |
| * generally the contents editpart is considered to be selected. This list |
| * can be modified indirectly by calling other methods on the viewer. |
| * |
| * @return a list containing zero or more editparts |
| */ |
| List getSelectedEditParts(); |
| |
| /** |
| * This method is inherited from |
| * {@link org.eclipse.jface.viewers.ISelectionProvider ISelectionProvider}. |
| * This method should return a |
| * {@link org.eclipse.jface.viewers.StructuredSelection} containing one or |
| * more of the viewer's EditParts. If no editparts are selected, the |
| * {@link #getContents() contents} editpart is returned. |
| * |
| * @see org.eclipse.jface.viewers.ISelectionProvider#getSelection() |
| */ |
| ISelection getSelection(); |
| |
| /** |
| * Returns the viewer's selection manager. The selection manager has |
| * complete control over the viewer's representation of selection. It |
| * provides the {@link ISelection} for the viewer, and manages all changes |
| * to the current selection. |
| * |
| * @return the selection manager |
| * @since 3.2 |
| */ |
| SelectionManager getSelectionManager(); |
| |
| /** |
| * Returns the {@link Map} for associating <i>visual parts</i> with their |
| * <code>EditParts</code>. This map is used for hit-testing. Hit testing is |
| * performed by first determining which visual part is hit, and then mapping |
| * that part to an <code>EditPart</code>. What consistutes a <i>visual |
| * part</i> is viewer-specific. Examples include <code>Figures</code> and |
| * <code>TreeItems</code>. |
| * |
| * @return the visual part map |
| */ |
| Map getVisualPartMap(); |
| |
| /** |
| * Used for accessibility purposes. |
| * |
| * @param acc |
| * the AccessibleEditPart |
| */ |
| void registerAccessibleEditPart(AccessibleEditPart acc); |
| |
| /** |
| * Removes the specified drag source listener. If all listeners are removed, |
| * the DragSource that was created will be disposed. |
| * |
| * @see #addDragSourceListener(TransferDragSourceListener) |
| * @param listener |
| * the listener |
| * @deprecated |
| */ |
| void removeDragSourceListener( |
| org.eclipse.gef.dnd.TransferDragSourceListener listener); |
| |
| /** |
| * Removes the specified drag source listener. If all listeners are removed, |
| * the DragSource that was created will be disposed. |
| * |
| * @see #addDragSourceListener(TransferDragSourceListener) |
| * @param listener |
| * the listener |
| */ |
| void removeDragSourceListener(TransferDragSourceListener listener); |
| |
| /** |
| * Removes the specified drop target listener. If all listeners are removed, |
| * the DropTarget that was created will be disposed. |
| * |
| * @see #addDropTargetListener(TransferDropTargetListener) |
| * @param listener |
| * @deprecated |
| */ |
| void removeDropTargetListener( |
| org.eclipse.gef.dnd.TransferDropTargetListener listener); |
| |
| /** |
| * Removes the specified drop target listener. If all listeners are removed, |
| * the DropTarget that was created will be disposed. |
| * |
| * @see #addDropTargetListener(TransferDropTargetListener) |
| * @param listener |
| * the listener |
| */ |
| void removeDropTargetListener(TransferDropTargetListener listener); |
| |
| /** |
| * removes the first instance of the specified property listener. |
| * |
| * @param listener |
| * the listener to remove |
| */ |
| void removePropertyChangeListener(PropertyChangeListener listener); |
| |
| /** |
| * Reveals the given EditPart if it is not visible. |
| * |
| * @param editpart |
| * the EditPart to reveal |
| */ |
| void reveal(EditPart editpart); |
| |
| /** |
| * Replaces the current selection with the specified <code>EditPart</code>. |
| * That part becomes the primary selection. Fires selection changed to |
| * {@link org.eclipse.jface.viewers.ISelectionChangedListener}s. |
| * |
| * @param editpart |
| * the new selection |
| */ |
| void select(EditPart editpart); |
| |
| /** |
| * Sets the contents for this Viewer. The contents can also be set using |
| * {@link #setContents(Object)}. |
| * |
| * @param editpart |
| * the contents |
| * @see #getRootEditPart() |
| */ |
| void setContents(EditPart editpart); |
| |
| /** |
| * Creates an <code>EditPart</code> for the provided model object using the |
| * <code>EditPartFactory</code>. That EditPart is then added to the |
| * {@link #getRootEditPart() RootEditPart}, and becomes the viewer's |
| * contents editpart. |
| * |
| * @param contents |
| * the contents model object |
| */ |
| void setContents(Object contents); |
| |
| /** |
| * Sets the context <code>MenuManager</code> for this viewer. The |
| * MenuManager will be asked to create a Menu, which will be used as the |
| * context menu for this viewer's Control. |
| * |
| * @param contextMenu |
| * the <code>ContextMenuProvider</code> |
| */ |
| void setContextMenu(MenuManager contextMenu); |
| |
| /** |
| * Sets the <code>Control</code> for this viewer. The viewer's control is |
| * also set automatically if {@link #createControl(Composite)} is called. |
| * |
| * @param control |
| * the Control |
| */ |
| void setControl(Control control); |
| |
| /** |
| * Sets the cursor for the viewer's <code>Control</code>. This method should |
| * only be called by {@link Tool Tools}. <code>null</code> can be used to |
| * indicate that the default cursor should be restored. |
| * |
| * @param cursor |
| * <code>null</code> or a Cursor |
| * @see #getControl() |
| */ |
| void setCursor(Cursor cursor); |
| |
| /** |
| * Sets the <code>EditDomain</code> for this viewer. The Viewer will route |
| * all mouse and keyboard events to the EditDomain. |
| * |
| * @param domain |
| * The EditDomain |
| */ |
| void setEditDomain(EditDomain domain); |
| |
| /** |
| * Sets the EditPartFactory. |
| * |
| * @param factory |
| * the factory |
| * @see #getEditPartFactory() |
| */ |
| void setEditPartFactory(EditPartFactory factory); |
| |
| /** |
| * Sets the <i>focus</i> EditPart. |
| * |
| * @see #getFocusEditPart() |
| * @param focus |
| * the FocusPart. |
| */ |
| void setFocus(EditPart focus); |
| |
| /** |
| * Sets the <code>KeyHandler</code>. |
| * |
| * @param keyHandler |
| * the KeyHandler |
| * @see #getKeyHandler() |
| */ |
| void setKeyHandler(KeyHandler keyHandler); |
| |
| /** |
| * Sets a property on this viewer. A viewer property is an arbitrary |
| * key-value pair that can be observed via |
| * {@link #addPropertyChangeListener(PropertyChangeListener)}. A |
| * <code>null</code> value will remove the property from the viewer. |
| * |
| * @param propertyName |
| * a unique string identifying the property |
| * @param value |
| * the properties new value or <code>null</code> to remove |
| * @since 3.0 |
| */ |
| void setProperty(String propertyName, Object value); |
| |
| /** |
| * Sets the <i>root</i> of this viewer. The root should not be confused with |
| * the <i>contents</i>. |
| * |
| * @param root |
| * the RootEditPart |
| * @see #getRootEditPart() |
| * @see #getContents() |
| */ |
| void setRootEditPart(RootEditPart root); |
| |
| /** |
| * Turns on/off the routing of events directly to the Editor. If supported |
| * by the viewer implementation, all Events should be routed to the |
| * <code>EditDomain</code> rather than handled in the default way. |
| * |
| * @param value |
| * true if the viewer should route events to the EditDomain |
| */ |
| void setRouteEventsToEditDomain(boolean value); |
| |
| /** |
| * Sets the selection manager for this viewer. |
| * |
| * @param manager |
| * the new selection manager |
| * @since 3.2 |
| */ |
| void setSelectionManager(SelectionManager manager); |
| |
| /** |
| * Used for accessibility purposes. |
| * |
| * @param acc |
| * the accessible part |
| */ |
| void unregisterAccessibleEditPart(AccessibleEditPart acc); |
| |
| } |