Eclipse GEF
2.1

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 EditParts, the conceptual objects with which the User interacts. The Viewer is responsible for:

When the Viewer is realized, meaning it has an SWT Control, it should activate its RootEditPart. When that Control is being disposed, it should EditPart.deactivate() the root.

Visuals is the term used to describe how EditParts are manifested to the User. Figures and TreeItems are examples of visuals support by the EditPartViewers included with GEF. The Viewer creates the necessary infrastructure for hosting its EditParts' visuals.

The Viewer maintains a list of selected EditParts. The last EditPart in this list is said to have primary selection. Focus is also maintained by the viewer. Focus can be changed without affecting the current selection. This is used for keyboard accessibility. The Viewer is responsible for reflecting the current focus and selection on its EditParts by calling EditPart.setFocus(boolean) and EditPart.setSelected(int).


Nested Class Summary
static interface EditPartViewer.Conditional
           
 
Method Summary
 void addDragSourceListener(TransferDragSourceListener listener)
          Adds a TransferDragSourceListener to this viewer.
 void addDropTargetListener(TransferDropTargetListener listener)
          Adds a TransferDropTargetListener to this viewer.
 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(org.eclipse.draw2d.geometry.Point location)
          Returns null or the EditPart associated with the specified location.
 EditPart findObjectAtExcluding(org.eclipse.draw2d.geometry.Point location, Collection exclusionSet)
          Returns null or the EditPart at the specified location, excluding the specified set.
 EditPart findObjectAtExcluding(org.eclipse.draw2d.geometry.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 the MenuManager for this viewer or null if no provider exists.
 Control getControl()
          Returns 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.
 RootEditPart getRootEditPart()
          Returns the RootEditPart.
 List getSelectedEditParts()
          Returns an unmodifiable List containing the selected editparts.
 Map getVisualPartMap()
          Returns the Map for associating visual parts with their EditParts.
 void registerAccessibleEditPart(AccessibleEditPart acc)
          Used for accessibility purposes.
 void reveal(EditPart editpart)
          Shows 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 for this Viewer.
 void setContents(Object contents)
          Creates an EditPart for the specified contents using this viewer's EditPartFactory.
 void setContextMenu(MenuManager contextMenu)
          Sets the MenuManager for this viewer's context menu.
 void setControl(Control control)
          Optionally 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 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 unregisterAccessibleEditPart(AccessibleEditPart acc)
          Used for accessibility purposes
 
Methods inherited from interface org.eclipse.jface.viewers.ISelectionProvider
addSelectionChangedListener, getSelection, removeSelectionChangedListener, setSelection
 

Method Detail

addDragSourceListener

public void addDragSourceListener(TransferDragSourceListener listener)
Adds a TransferDragSourceListener to this viewer. This has the side-effect of ensuring that a DragSource exists for the viewer's Control.

Parameters:
listener - the listener

addDropTargetListener

public void addDropTargetListener(TransferDropTargetListener listener)
Adds a TransferDropTargetListener to this viewer. This has the side-effect of ensuring that a DropTarget exists for the viewer's Control.

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

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(org.eclipse.draw2d.geometry.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(org.eclipse.draw2d.geometry.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(org.eclipse.draw2d.geometry.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 the MenuManager for this viewer or null if no provider exists.

Returns:
the MenuManager

getControl

public Control getControl()
Returns the SWT Control for this viewer.

Returns:
the SWT Control

getEditDomain

public EditDomain getEditDomain()
Returns the EditDomain to which this viewer belongs

Returns:
the 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 then used by all EditParts that need to create additional EditParts, such as children.

Returns:
EditPartFactory

getEditPartRegistry

public Map getEditPartRegistry()
Returns the Map for registering EditParts by Keys. EditParts may register themselves using any method, and may register themselved multiple times. The purpose of such registration is to allow an EditPart to be found by other EditParts.

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.

Returns:
the focus EditPart

getKeyHandler

public KeyHandler getKeyHandler()
Returns the KeyHandler for this viewer. The KeyHandler is forwarded keys by the 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:
KeyHandler

getRootEditPart

public RootEditPart getRootEditPart()
Returns the RootEditPart. The RootEditPart is a special EditPart that bridges the connection to the viewer. 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.

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

getSelectedEditParts

public List getSelectedEditParts()
Returns an unmodifiable List containing the selected editparts.

Returns:
the selected parts

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

reveal

public void reveal(EditPart editpart)
Shows 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 for this Viewer.

See Also:
getRootEditPart()

setContents

public void setContents(Object contents)
Creates an EditPart for the specified contents using this viewer's EditPartFactory. That EditPart is then added to the RootEditPart.

Parameters:
contents - the Object representing the viewer's contents
See Also:
setEditPartFactory(EditPartFactory)

setContextMenu

public void setContextMenu(MenuManager contextMenu)
Sets the MenuManager for this viewer's context menu. This MenuManager creates the SWT Menu for this viewer's control.

Parameters:
contextMenu - the ContextMenuProvider
See Also:
getControl()

setControl

public void setControl(Control control)
Optionally 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()

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

unregisterAccessibleEditPart

public void unregisterAccessibleEditPart(AccessibleEditPart acc)
Used for accessibility purposes

Parameters:
acc - the accessible part

Eclipse GEF
2.1

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