Eclipse GEF and Draw2d Plug-in Developer Guide (Galileo) - EditPartViewer (Eclipse GEF API Specification)

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 (java.beans.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, java.util.Collection exclusionSet)
          Returns null or the EditPart at the specified location, excluding the specified set.

EditPart findObjectAtExcluding ( Point location, java.util.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.

java.util.Map getEditPartRegistry ()
          Returns the Map for registering EditParts by Keys.

EditPart getFocusEditPart ()
          Returns the focus EditPart.

KeyHandler getKeyHandler ()
          Returns the KeyHandler for this viewer.

java.lang.Object getProperty (java.lang.String key)
          Returns the value of the given property.

ResourceManager getResourceManager ()
          Returns null, or the ResourceManager for this Viewer.

RootEditPart getRootEditPart ()
          Returns the RootEditPart.

java.util.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.

java.util.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 (java.beans.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 (java.lang.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 (java.lang.String propertyName, java.lang.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(java.beans.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 ISelectionChangedListeners.

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 ISelectionChangedListeners.

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 ISelectionChangedListeners.

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,
                                      java.util.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,
                                      java.util.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 java.util.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 java.lang.Object getProperty(java.lang.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 java.util.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 java.util.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(java.beans.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 ISelectionChangedListeners.

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(java.lang.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(java.lang.String propertyName,
                        java.lang.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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse GEF
3.3

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.gef Interface EditPartViewer

addDragSourceListener

addDragSourceListener

addDropTargetListener

addDropTargetListener

addPropertyChangeListener

appendSelection

createControl

deselect

deselectAll

findObjectAt

findObjectAtExcluding

findObjectAtExcluding

flush

getContents

getContextMenu

getControl

getEditDomain

getEditPartFactory

getEditPartRegistry

getFocusEditPart

getKeyHandler

getProperty

getResourceManager

getRootEditPart

getSelectedEditParts

getSelection

getSelectionManager

getVisualPartMap

registerAccessibleEditPart

removeDragSourceListener

removeDragSourceListener

removeDropTargetListener

removeDropTargetListener

removePropertyChangeListener

reveal

select

setContents

setContents

setContextMenu

setControl

setCursor

setEditDomain

setEditPartFactory

setFocus

setKeyHandler

setProperty

setRootEditPart

setRouteEventsToEditDomain

setSelectionManager

unregisterAccessibleEditPart

org.eclipse.gef
Interface EditPartViewer