Eclipse GEF 3.3

## org.eclipse.gef
Interface EditPartViewer

All Superinterfaces:
  ISelectionProvider

All Known Subinterfaces:
  GraphicalViewer

All Known Implementing Classes:
  AbstractEditPartViewer, GraphicalViewerImpl

public interface EditPartViewer
extends ISelectionProvider

An adapter on an SWT `Control` that manages the `EditParts`. The viewer is responsible for the editpart lifecycle. Editparts have visuals, such as `TreeItems` or `Figures`, which are hosted by the viewer and its control. The viewer provides targeting of editparts via their visuals.

A viewer is a `ISelectionProvider`. It maintains a list of selected editparts. The last member of this list is the primary member of the selection. The list should never be empty; when no editparts are selected, the viewer's contents editpart is used.

A viewer is populated by setting its contents. This can be done by passing the model corresponding to the contents. The viewer's `EditPartFactory` is then used to create the contents editpart, and add it to the root 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 `EditPart.refresh()` method.

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 `RootEditPart`.

An editpart's lifecycle is managed by the viewer. When the Viewer is realized, meaning it has an SWT `Control`, 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.

A Viewer has an arbitrary collection of keyed properties that can be set and queried. A value of `null` is used to remove a key from the property map. A viewer will fire property change notification whenever these values are updated.

WARNING: This interface is not intended to be implemented. Clients should extend `AbstractEditPartViewer`.

Nested Class Summary
`static interface` `EditPartViewer.Conditional` An object which evaluates an EditPart for an arbitrary property.

Method Summary
`void` `addDragSourceListener(TransferDragSourceListener listener)` Provided for compatibility with existing code.
`void` `addDragSourceListener(TransferDragSourceListener listener)` Adds a `TransferDragSourceListener` to this viewer.
`void` `addDropTargetListener(TransferDropTargetListener listener)` Provided for compatibility with existing code.
`void` `addDropTargetListener(TransferDropTargetListener listener)` Adds a `TransferDropTargetListener` to this viewer.
`void` `addPropertyChangeListener(PropertyChangeListener listener)` Adds a listener to be notified of viewer property changes.
`void` `appendSelection(EditPart editpart)` Appends the specified `EditPart` to the viewer's selection.
`Control` `createControl(Composite composite)` Optionally creates the default `Control` using the default style.
`void` `deselect(EditPart editpart)` Removes the specified `EditPart` from the current selection.
`void` `deselectAll()` Deselects all EditParts.
`EditPart` `findObjectAt(Point location)` Returns `null` or the `EditPart` associated with the specified location.
`EditPart` `findObjectAtExcluding(Point location, Collection exclusionSet)` Returns `null` or the `EditPart` at the specified location, excluding the specified set.
`EditPart` `findObjectAtExcluding(Point location, Collection exclusionSet, EditPartViewer.Conditional conditional)` Returns `null` or the `EditPart` at the specified location, using the given exclusion set and conditional.
`void` `flush()` Flushes all pending updates to the Viewer.
`EditPart` `getContents()` Returns the contents of this Viewer.
`MenuManager` `getContextMenu()` Returns `null` or the MenuManager for this viewer.
`Control` `getControl()` Returns `null` or the SWT `Control` for this viewer.
`EditDomain` `getEditDomain()` Returns the `EditDomain` to which this viewer belongs.
`EditPartFactory` `getEditPartFactory()` Returns the `EditPartFactory` for this viewer.
`Map` `getEditPartRegistry()` Returns the `Map` for registering `EditParts` by Keys.
`EditPart` `getFocusEditPart()` Returns the focus `EditPart`.
`KeyHandler` `getKeyHandler()` Returns the `KeyHandler` for this viewer.
`Object` `getProperty(String key)` Returns the value of the given property.
`ResourceManager` `getResourceManager()` Returns `null`, or the ResourceManager for this Viewer.
`RootEditPart` `getRootEditPart()` Returns the `RootEditPart`.
`List` `getSelectedEditParts()` Returns an unmodifiable `List` containing zero or more selected editparts.
`ISelection` `getSelection()` This method is inherited from `ISelectionProvider`.
`SelectionManager` `getSelectionManager()` Returns the viewer's selection manager.
`Map` `getVisualPartMap()` Returns the `Map` for associating visual parts with their `EditParts`.
`void` `registerAccessibleEditPart(AccessibleEditPart acc)` Used for accessibility purposes.
`void` `removeDragSourceListener(TransferDragSourceListener listener)` Deprecated.
`void` `removeDragSourceListener(TransferDragSourceListener listener)` Removes the specified drag source listener.
`void` `removeDropTargetListener(TransferDropTargetListener listener)` Deprecated.
`void` `removeDropTargetListener(TransferDropTargetListener listener)` Removes the specified drop target listener.
`void` `removePropertyChangeListener(PropertyChangeListener listener)` removes the first instance of the specified property listener.
`void` `reveal(EditPart editpart)` Reveals the given EditPart if it is not visible.
`void` `select(EditPart editpart)` Replaces the current selection with the specified `EditPart`.
`void` `setContents(EditPart editpart)` Sets the contents for this Viewer.
`void` `setContents(Object contents)` Creates an `EditPart` for the provided model object using the `EditPartFactory`.
`void` `setContextMenu(MenuManager contextMenu)` Sets the context `MenuManager` for this viewer.
`void` `setControl(Control control)` Sets the `Control` for this viewer.
`void` `setCursor(Cursor cursor)` Sets the cursor for the viewer's `Control`.
`void` `setEditDomain(EditDomain domain)` Sets the `EditDomain` for this viewer.
`void` `setEditPartFactory(EditPartFactory factory)` Sets the EditPartFactory.
`void` `setFocus(EditPart focus)` Sets the focus EditPart.
`void` `setKeyHandler(KeyHandler keyHandler)` Sets the `KeyHandler`.
`void` `setProperty(String propertyName, Object value)` Sets a property on this viewer.
`void` `setRootEditPart(RootEditPart root)` Sets the root of this viewer.
`void` `setRouteEventsToEditDomain(boolean value)` Turns on/off the routing of events directly to the Editor.
`void` `setSelectionManager(SelectionManager manager)` Sets the selection manager for this viewer.
`void` `unregisterAccessibleEditPart(AccessibleEditPart acc)` Used for accessibility purposes.

Methods inherited from interface org.eclipse.jface.viewers.ISelectionProvider
`addSelectionChangedListener, removeSelectionChangedListener, setSelection`

Method Detail

### addDragSourceListener

    public void addDragSourceListener(TransferDragSourceListener listener)

  Provided for compatibility with existing code.

  Parameters:
    `listener` - a drag source listener
  See Also:
    `addDragSourceListener(TransferDragSourceListener)`

### addDragSourceListener

    public void addDragSourceListener(TransferDragSourceListener listener)

  Adds a `TransferDragSourceListener` to this viewer. This has the side-effect of creating a `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.

  Parameters:
    `listener` - the listener

### addDropTargetListener

    public void addDropTargetListener(TransferDropTargetListener listener)

  Provided for compatibility with existing code.

  Parameters:
    `listener` - the listener
  See Also:
    `addDropTargetListener(TransferDropTargetListener)`

### addDropTargetListener

    public void addDropTargetListener(TransferDropTargetListener listener)

  Adds a `TransferDropTargetListener` to this viewer. This has the side-effect of creating a `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.

  Parameters:
    `listener` - the listener

### addPropertyChangeListener

    public void addPropertyChangeListener(PropertyChangeListener listener)

  Adds a listener to be notified of viewer property changes.

  Parameters:
    `listener` - the listener

### appendSelection

    public void appendSelection(EditPart editpart)

  Appends the specified `EditPart` to the viewer's selection. The EditPart becomes the new primary selection. Fires selection changed to all `ISelectionChangedListener`s.

  Parameters:
    `editpart` - the EditPart to append

### createControl

    public Control createControl(Composite composite)

  Optionally creates the default `Control` using the default style. The Control can also be created externally and then set into the Viewer.

  Parameters:
    `composite` - the parent in which create the SWT `Control`
  Returns:
    the created Control for convenience
  See Also:
    `setControl(Control)`

### deselect

    public void deselect(EditPart editpart)

  Removes the specified `EditPart` from the current selection. If the selection becomes empty, the viewer's `contents` becomes the current selected part. The last EditPart in the new selection is made `primary`.

  Fires selection changed to `ISelectionChangedListener`s.

  Parameters:
    `editpart` - the `EditPart` to deselect

### deselectAll

    public void deselectAll()

  Deselects all EditParts. The viewer's `contents` becomes the current selection. Fires selection changed to `ISelectionChangedListener`s.

### findObjectAt

    public EditPart findObjectAt(Point location)

  Returns `null` or the `EditPart` associated with the specified location. The location is relative to the client area of the Viewer's `Control`. An EditPart is not directly visible. It is targeted using its visual part which it registered using the `visual part map`. What constitutes a visual part is viewer-specific. Examples include Figures and TreeItems.

  Parameters:
    `location` - The location
  Returns:
    `null` or an EditPart

### findObjectAtExcluding

    public EditPart findObjectAtExcluding(Point location,
                                          Collection exclusionSet)

  Returns `null` or the `EditPart` at the specified location, excluding the specified set. This method behaves similarly to `findObjectAt(Point)`.

  Parameters:
    `location` - The mouse location
    `exclusionSet` - The set of EditParts to be excluded
  Returns:
    `null` or an EditPart

### findObjectAtExcluding

    public EditPart findObjectAtExcluding(Point location,
                                          Collection exclusionSet,
                                          EditPartViewer.Conditional conditional)

  Returns `null` or the `EditPart` at the specified location, using the given exclusion set and conditional. This method behaves similarly to `findObjectAt(Point)`.

  Parameters:
    `location` - The mouse location
    `exclusionSet` - The set of EditParts to be excluded
    `conditional` - the Conditional used to evaluate a potential hit
  Returns:
    `null` or an EditPart

### flush

    public void flush()

  Flushes all pending updates to the Viewer.

### getContents

    public EditPart getContents()

  Returns the contents 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 contents is implicitly the selected object.

  The Root of the Viewer is different. By constrast, the root is never selected or targeted, and does not correspond to something in the model.

  Returns:
    the contents `EditPart`
  See Also:
    `getRootEditPart()`

### getContextMenu

    public MenuManager getContextMenu()

  Returns `null` or the MenuManager for this viewer. The menu manager is set using `setContextMenu(MenuManager)`.

  Returns:
    `null` or a MenuManager

### getControl

    public Control getControl()

  Returns `null` or the SWT `Control` for this viewer. The control is either set explicitly or can be created by the viewer.

  Returns:
    the SWT `Control`
  See Also:
    `setControl(Control)`, `createControl(Composite)`

### getEditDomain

    public EditDomain getEditDomain()

  Returns the `EditDomain` to which this viewer belongs.

  Returns:
    the viewer's EditDomain

### getEditPartFactory

    public EditPartFactory getEditPartFactory()

  Returns the `EditPartFactory` for this viewer. The EditPartFactory is used to create the contents EditPart when `setContents(Object)` is called. It is made available so that other EditParts can use it to create their children or connection editparts.

  Returns:
    EditPartFactory

### getEditPartRegistry

    public Map getEditPartRegistry()

  Returns the `Map` for registering `EditParts` by Keys. 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.

  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.

  Returns:
    the registry map

### getFocusEditPart

    public EditPart getFocusEditPart()

  Returns the focus `EditPart`. 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 `null`.

  Returns:
    the focus `EditPart`

### getKeyHandler

    public KeyHandler getKeyHandler()

  Returns the `KeyHandler` for this viewer. The KeyHandler is sent KeyEvents by the currently active `Tool`. 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 `SelectionTool` forwards keysrokes. It does not do so during a drag.

  Returns:
    `null` or a KeyHandler

### getProperty

    public Object getProperty(String key)

  Returns the value of the given property. Returns `null` if the property has not been set, or has been set to null.

  Parameters:
    `key` - the property's key
  Returns:
    the given properties value or `null`.

### getResourceManager

    public ResourceManager getResourceManager()

  Returns `null`, 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.

  Typical usage is by EditParts contained inside the viewer. EditParts which are removed from the viewer should free their resources during `EditPart.removeNotify()`. When the viewer is disposed, `removeNotify()` is not called, but the viewer's resource manager will be disposed anyway.

  The viewer's default resource manager is linked to JFace's `global shared resources`.

  Returns:
    the ResourceManager associated with this viewer
  Since:
    3.3

### getRootEditPart

    public RootEditPart getRootEditPart()

  Returns the `RootEditPart`. The RootEditPart is a special EditPart that serves as the parent to the contents editpart. The root is never selected. The root does not correspond to anything in the model. The User does not interact with the root.

  The RootEditPart has a single child: the `contents`.

  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.

  Returns:
    the RootEditPart
  See Also:
    `getContents()`, `setRootEditPart(RootEditPart)`

### getSelectedEditParts

    public List getSelectedEditParts()

  Returns an unmodifiable `List` containing zero or more selected editparts. This list may be empty. In contrast, the inherited method `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.

  Returns:
    a list containing zero or more editparts

### getSelection

    public ISelection getSelection()

  This method is inherited from `ISelectionProvider`. This method should return a `StructuredSelection` containing one or more of the viewer's EditParts. If no editparts are selected, the `contents` editpart is returned.

  Specified by:
    `getSelection` in interface `ISelectionProvider`
  See Also:
    `ISelectionProvider.getSelection()`

### getSelectionManager

    public SelectionManager getSelectionManager()

  Returns the viewer's selection manager. The selection manager has complete control over the viewer's representation of selection. It provides the `ISelection` for the viewer, and manages all changes to the current selection.

  Returns:
    the selection manager
  Since:
    3.2

### getVisualPartMap

    public Map getVisualPartMap()

  Returns the `Map` for associating visual parts with their `EditParts`. 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 `EditPart`. What consistutes a visual part is viewer-specific. Examples include `Figures` and `TreeItems`.

  Returns:
    the visual part map

### registerAccessibleEditPart

    public void registerAccessibleEditPart(AccessibleEditPart acc)

  Used for accessibility purposes.

  Parameters:
    `acc` - the AccessibleEditPart

### removeDragSourceListener

    public void removeDragSourceListener(TransferDragSourceListener listener)

  Deprecated.

  Removes the specified drag source listener. If all listeners are removed, the DragSource that was created will be disposed.

  Parameters:
    `listener` - the listener
  See Also:
    `addDragSourceListener(TransferDragSourceListener)`

### removeDragSourceListener

    public void removeDragSourceListener(TransferDragSourceListener listener)

  Removes the specified drag source listener. If all listeners are removed, the DragSource that was created will be disposed.

  Parameters:
    `listener` - the listener
  See Also:
    `addDragSourceListener(TransferDragSourceListener)`

### removeDropTargetListener

    public void removeDropTargetListener(TransferDropTargetListener listener)

  Deprecated.

  Removes the specified drop target listener. If all listeners are removed, the DropTarget that was created will be disposed.

  Parameters:
    `listener` -
  See Also:
    `addDropTargetListener(TransferDropTargetListener)`

### removeDropTargetListener

    public void removeDropTargetListener(TransferDropTargetListener listener)

  Removes the specified drop target listener. If all listeners are removed, the DropTarget that was created will be disposed.

  Parameters:
    `listener` - the listener
  See Also:
    `addDropTargetListener(TransferDropTargetListener)`

### removePropertyChangeListener

    public void removePropertyChangeListener(PropertyChangeListener listener)

  removes the first instance of the specified property listener.

  Parameters:
    `listener` - the listener to remove

### reveal

    public void reveal(EditPart editpart)

  Reveals the given EditPart if it is not visible.

  Parameters:
    `editpart` - the EditPart to reveal

### select

    public void select(EditPart editpart)

  Replaces the current selection with the specified `EditPart`. That part becomes the primary selection. Fires selection changed to `ISelectionChangedListener`s.

  Parameters:
    `editpart` - the new selection

### setContents

    public void setContents(EditPart editpart)

  Sets the contents for this Viewer. The contents can also be set using `setContents(Object)`.

  Parameters:
    `editpart` - the contents
  See Also:
    `getRootEditPart()`

### setContents

    public void setContents(Object contents)

  Creates an `EditPart` for the provided model object using the `EditPartFactory`. That EditPart is then added to the `RootEditPart`, and becomes the viewer's contents editpart.

  Parameters:
    `contents` - the contents model object

### setContextMenu

    public void setContextMenu(MenuManager contextMenu)

  Sets the context `MenuManager` 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.

  Parameters:
    `contextMenu` - the `ContextMenuProvider`

### setControl

    public void setControl(Control control)

  Sets the `Control` for this viewer. The viewer's control is also set automatically if `createControl(Composite)` is called.

  Parameters:
    `control` - the Control

### setCursor

    public void setCursor(Cursor cursor)

  Sets the cursor for the viewer's `Control`. This method should only be called by `Tools`. `null` can be used to indicate that the default cursor should be restored.

  Parameters:
    `cursor` - `null` or a Cursor
  See Also:
    `getControl()`

### setEditDomain

    public void setEditDomain(EditDomain domain)

  Sets the `EditDomain` for this viewer. The Viewer will route all mouse and keyboard events to the EditDomain.

  Parameters:
    `domain` - The EditDomain

### setEditPartFactory

    public void setEditPartFactory(EditPartFactory factory)

  Sets the EditPartFactory.

  Parameters:
    `factory` - the factory
  See Also:
    `getEditPartFactory()`

### setFocus

    public void setFocus(EditPart focus)

  Sets the focus EditPart.

  Parameters:
    `focus` - the FocusPart.
  See Also:
    `getFocusEditPart()`

### setKeyHandler

    public void setKeyHandler(KeyHandler keyHandler)

  Sets the `KeyHandler`.

  Parameters:
    `keyHandler` - the KeyHandler
  See Also:
    `getKeyHandler()`

### setProperty

    public void setProperty(String propertyName,
                            Object value)

  Sets a property on this viewer. A viewer property is an arbitrary key-value pair that can be observed via `addPropertyChangeListener(PropertyChangeListener)`. A `null` value will remove the property from the viewer.

  Parameters:
    `propertyName` - a unique string identifying the property
    `value` - the properties new value or `null` to remove
  Since:
    3.0

### setRootEditPart

    public void setRootEditPart(RootEditPart root)

  Sets the root of this viewer. The root should not be confused with the contents.

  Parameters:
    `root` - the RootEditPart
  See Also:
    `getRootEditPart()`, `getContents()`

### setRouteEventsToEditDomain

    public void setRouteEventsToEditDomain(boolean value)

  Turns on/off the routing of events directly to the Editor. If supported by the viewer implementation, all Events should be routed to the `EditDomain` rather than handled in the default way.

  Parameters:
    `value` - true if the viewer should route events to the EditDomain

### setSelectionManager

    public void setSelectionManager(SelectionManager manager)

  Sets the selection manager for this viewer.

  Parameters:
    `manager` - the new selection manager
  Since:
    3.2

### unregisterAccessibleEditPart

    public void unregisterAccessibleEditPart(AccessibleEditPart acc)

  Used for accessibility purposes.

  Parameters:
    `acc` - the accessible part

Eclipse GEF 3.3

Copyright (c) IBM Corp. and others 2000, 2007. All Rights Reserved.