de.tu_berlin.cs.tfs.muvitorkit.ui
Class MuvitorPage

java.lang.Object
  extended by org.eclipse.ui.part.Page
      extended by de.tu_berlin.cs.tfs.muvitorkit.ui.MuvitorPage
All Implemented Interfaces:
IGraphicalViewerProvider, EventListener, IAdaptable, CommandStackListener, ISelectionListener, IPage, IPageBookViewPage

public abstract class MuvitorPage
extends Page
implements IAdaptable, CommandStackListener, IGraphicalViewerProvider, ISelectionListener

This is an IPage that contains some GraphicalViewers as well as a FlyoutPaletteComposite and that manages changing of the current viewer. It is meant to be used in a MuvitorPageBookView like a regular graphical GEF editor. Like an GEF editor this page has its own EditDomain and ActionRegistry but uses the CommandStack and some general action instances (which we call shared) from the main MuvitorTreeEditor.

On calling MuvitorTreeEditor.showView(String, EObject)) with the ID (as in plugin.xml) of this page's parent MuvitorPageBookView, the top model element and a parent editor are set in the constructor. A ZoomManagerDelegate for a ZoomComboContributionItem is provided via getAdapter(Class) to the workbench page's part service.

This class should be used in the MuvitorKit (with a central MuvitorTreeEditor) only. But for documentation, the following enumerates what the main editor provides to this page via getAdapter():

When initialized and in createControl(Composite) this class does the following:

  1. The page registers itself as an EMF eAdapter to the EObject model to be able to react on notifications of the EMF model. Subclasses may use this as described below.
  2. The page registers itself as an CommandStackListener on the editor's CommandStack to update actions on command stack changes.
  3. A FlyoutPaletteComposite is being created which uses the Preferences of the Plugin delivered by the parent editor.
  4. Some MuvitorPage.MultiViewerPageViewers (the number depends on getViewerContents() are being created and added to the SelectionSynchronizer delivered by the parent editor. The objects returned by getViewerContents() are set as contents of these viewers.
  5. A ScrollableThumbnail showing a miniature overview of the current viewer is being installed below the palette.
  6. The first viewer is set as the current viewer.
  7. Actions are being created: ZoomInAction, ZoomOutAction and custom Actions defined in the abstract method createCustomActions(). Handles for some standard RetargetActions from the ActionFactory besides zooming and undo/redo are being registered if they have been created in createCustomActions(): COPY, CUT, PASTE, DELETE.

For a guide on how to create custom actions have a look at the documentation of createCustomActions().

This page uses an own minimally modified kind of edit part viewer, the MuvitorPage.MultiViewerPageViewer. Such a viewer notices if a mouse click occurs on it and sets itself as the current viewer which performs the following updates by calling setCurrentViewer(MultiViewerPageViewer) for itself:

  1. The clicked viewer is set as ISelectionProvider of the IPageSite, so all components and in particular all SelectionActions of the editor are aware of the current selection in the current viewer.
  2. The page registers itself as an ISelectionChangedListener on the viewer to be able to update the UpdateActions in its ActionRegistry on selection changes.
  3. The ScrollableThumbnail is being redirected to show the new current viewer.
  4. The ZoomManager of the clicked viewer is set as delegating target in the ZoomManagerDelegate, so the central ZoomComboContributionItem in the editor's action bar acts on the currently selected viewer.
The contents of an existing viewer may be replaced with another object via setViewersContents(int, EObject). As well, you may hide or restore a particular viewer on this page with setViewerVisibility(int, boolean)

The following methods have to be implemented by subclasses. Consider the documentation of each method as well, as they provide some hints!

This page is prepared to work with the MuvitorKits animation package; it implements the IGraphicalViewerProvider interface.

Originally, this class was considered to roughly work like GraphicalEditorWithFlyoutPalette.

Rating red

Nested Class Summary
 class MuvitorPage.MultiViewerPageViewer
          This local class extends ScrollingGraphicalViewer by a MouseListener that sets this viewer as the page's current viewer when a mouse click occurs on this viewer.
static class MuvitorPage.MuvitorRulerProvider
           
 
Constructor Summary
MuvitorPage(MuvitorPageBookView view)
           
 
Method Summary
 void commandStackChanged(EventObject event)
          If some command manipulates the model and is put to the command stack the actions are updated.
protected abstract  ContextMenuProviderWithActionRegistry createContextMenuProvider(EditPartViewer viewer)
          Subclasses must implement to specify the ContextMenuProviderWithActionRegistry that should be used by this page's GraphicalViewers and is responsible to show the created actions in the context menu.
 void createControl(Composite parent)
          This method creates all the visual parts and configures them: A FlyoutPaletteComposite is created and associated with the Preferences of the #editor's Plugin.
protected abstract  void createCustomActions()
          To be implemented by subclasses.
protected abstract  EditPartFactory createEditPartFactory()
          Subclasses must implement to specify the EditPartFactory that should be used by this page's GraphicalViewers.
protected abstract  MuvitorPaletteRoot createPaletteRoot()
          Subclasses must implement to specify the PaletteRoot that should be used by this page's EditDomain and which defines the contents of the palette.
 void dispose()
          Stops listening to the model, removes viewers from the #editor's SelectionSynchronizer, stops listening to the global selection service, and deactivates the thumbnail.
protected  ActionRegistry getActionRegistry()
           
 Object getAdapter(Class clazz)
          Extended to provide zoomManagerDelegate as ZoomManager.
 Control getControl()
           
 MuvitorPage.MultiViewerPageViewer getCurrentViewer()
           
 MuvitorTreeEditor getEditor()
           
 EObject getModel()
           
 int getNumberOfViewers()
           
protected  KeyHandler getSharedKeyHandler()
          Configures the keyHandler with standard key strokes like DEL (for DeleteAction) and F2 (for direct edit).
 IStatusLineManager getStatusLineManager()
          This can be used to display messages in this page's status line.
protected  int[] getThumbSashWeights()
          The two values in the returned array specify how the fly-out composite's space is being divided between the palette entries and the thumbnail in the palette.
 IToolBarManager getToolBarManager()
          This can be used to add actions to this page's tool bar.
 GraphicalViewer getViewer(EObject forModel)
          Method to get the viewer showing a specific model.
protected abstract  EObject[] getViewerContents()
          The viewer's are arranged horizontally and will be showing these objects in the order of the returned array from left to right.
protected  List<MuvitorPage.MultiViewerPageViewer> getViewers()
          Method to get the list of viewers if needed to implement advanced editor features.
 EObject getViewersContents(int viewerPosition)
          A method to access the object which is being displayed in a specific viewer.
 void init(IPageSite pageSite)
          Registers this page as eAdapter listener on its model and as listener on the parent MuvitorTreeEditor's CommandStack.
protected  void notifyChanged(Notification msg)
          By default, an Adapter will be registered with this page's model that passes notifications to this method, which subclasses are expected to override.
protected  IAction registerAction(IAction action)
          Registers an IAction instance with this page's ActionRegistry.
protected  IAction registerActionAsHandler(IAction action)
          Registers an IAction instance with this page's ActionRegistry and sets it as the handler action (in this page) for a RetargetAction that has been defined in the MuvitorActionBarContributor with the same ID as the action.
protected  IAction registerSharedAction(String id)
          Registers an IAction instance from the parent MuvitorTreeEditor's ActionRegistry with this page's action registry.
protected  IAction registerSharedActionAsHandler(String id)
          Registers an IAction instance from the parent editor's ActionRegistry with this page's action registry and sets it as the handler action (in this page) for a RetargetAction that has been defined in the MuvitorActionBarContributor with the same ID as the action.
 void selectionChanged(IWorkbenchPart part, ISelection selection)
          If a selection change occurs in the one of the editor components (possibly in the current viewer) the UpdateActions in this page's ActionRegistry are being updated.
protected  void setCurrentViewer(MuvitorPage.MultiViewerPageViewer viewer)
          This method sets the current graphical viewer of this page which implies that the passed viewer will be shown in the Thumbnail, becomes the current ISelectionProvider in the SelectionProviderIntermediate for this page's IPageSite and provides the ZoomManager for the zoom actions the ZoomManagerDelegate delegates to.
 void setFocus()
          Sets focus to a part in the page.
protected abstract  void setupKeyHandler(KeyHandler kh)
          Subclasses must implement to associate KeyStrokes with Actions in the passed KeyHandler which is the one used for the GraphicalViewers.
 void setViewersContents(int viewerPosition, EObject model)
          A method to set a new object to be shown in a specific viewer.
 void setViewerVisibility(int viewerPosition, boolean visible)
          This method sets the visibility of a viewer's control and relayouts the SashForm so that the visible viewers on it occupy the remaining space.
protected  void updateActions()
          Updates all UpdateActions registered in the actionRegistry.
 
Methods inherited from class org.eclipse.ui.part.Page
getSite, makeContributions, setActionBars
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MuvitorPage

public MuvitorPage(MuvitorPageBookView view)
Parameters:
view - the MuvitorPageBookView that hosts this page
Method Detail

getModel

public final EObject getModel()
Returns:
The model of this page (and its view)

init

public void init(IPageSite pageSite)
Registers this page as eAdapter listener on its model and as listener on the parent MuvitorTreeEditor's CommandStack.

Subclasses may extendto perform further initializations butm ust call super implementation! Remember to clean them up in dispose() if needed!.

Specified by:
init in interface IPageBookViewPage
Overrides:
init in class Page

createCustomActions

protected abstract void createCustomActions()
To be implemented by subclasses.

In his method, you can create IAction instances to be used in this page; in the viewers' context menu, by keys, or on the page's tool bar. For this, there are four methods that should cover all needs: registerAction(IAction), registerActionAsHandler(IAction), registerSharedAction(String), and registerSharedActionAsHandler(String). See their documentation for a description, when to use which method.

To put actions on the tool bar, you may add them to the tool bar manager (see getToolBarManager()) after registering.

WorkbenchPartActions and SelectionActions created here should get the editor (getEditor()) as workbench part in their constructor.

Consider sharing actions instances with the main editor, if possible!

See Also:
createActions()

registerAction

protected final IAction registerAction(IAction action)
Registers an IAction instance with this page's ActionRegistry.

Call this method in createCustomActions() if you want to use an action instance in the context menu or put it on the page's tool bar.

Do not use this method if you

Parameters:
action - the action to be registered
Returns:
the action for convenience
See Also:
createCustomActions(), createActions(), getToolBarManager()

registerActionAsHandler

protected final IAction registerActionAsHandler(IAction action)
Registers an IAction instance with this page's ActionRegistry and sets it as the handler action (in this page) for a RetargetAction that has been defined in the MuvitorActionBarContributor with the same ID as the action.

Call this method in createCustomActions() if you want to use an action instance (as a handler for a RetargetAction) in the context menu or put it on the page's tool bar.

Do not use this method if you

Technical remark: Registering handles has to be done only once since PageBookView.partActivated(org.eclipse.ui.IWorkbenchPart) takes care about refreshing the global action handlers for the ViewSite with the global action handlers defined for the SubActionBars of this IPageSite.

Parameters:
action - the action to be registered
Returns:
the action for convenience
See Also:
createCustomActions(), createActions(), getToolBarManager()

registerSharedAction

protected final IAction registerSharedAction(String id)
Registers an IAction instance from the parent MuvitorTreeEditor's ActionRegistry with this page's action registry.

Call this method in createCustomActions() if you want to reuse an action instance from the editor in the context menu or put it on the page's tool bar. Considering this for most Actions is strongly advised!

Do not use this method if you

Parameters:
id - the ID of the action to be retrieved from the parent editor's action registry
Returns:
the action from the parent editor for convenience
See Also:
createCustomActions(), createActions(), getToolBarManager()

registerSharedActionAsHandler

protected final IAction registerSharedActionAsHandler(String id)
Registers an IAction instance from the parent editor's ActionRegistry with this page's action registry and sets it as the handler action (in this page) for a RetargetAction that has been defined in the MuvitorActionBarContributor with the same ID as the action.

Call this method in createCustomActions() if you want to reuse an action handler for a RetargetAction from the editor in the context menu or put it on the page's tool bar. Considering this for most handle Actions is strongly advised!

Do not use this method if you

Technical remark: Registering handles has to be done only once since PageBookView.partActivated(org.eclipse.ui.IWorkbenchPart) takes care about refreshing the global action handlers for the ViewSite with the global action handlers defined for the SubActionBars of this IPageSite.

Parameters:
id - the ID of the action to be retrieved from the parent editor's action registry
Returns:
the action from the parent editor for convenience
See Also:
createCustomActions(), createActions(), getToolBarManager()

createControl

public final void createControl(Composite parent)
This method creates all the visual parts and configures them:
  1. A FlyoutPaletteComposite is created and associated with the Preferences of the #editor's Plugin.
  2. With createGraphicalViewerComposite() a composite hosting the MuvitorPage.MultiViewerPageViewers is being created and set as graphical control for the flyoutPaletteComposite.
  3. The ScrollableThumbnail is being created with installThumbnailInPalette().
  4. The first viewer in viewers is set with setCurrentViewer(MuvitorPage.MultiViewerPageViewer) .
  5. The selectionProvider intermediate is set as selection provider for this page's site.
  6. This page starts listening on the global selection service for selection changes.
  7. Actions are being created via createActions().

Specified by:
createControl in interface IPage
Specified by:
createControl in class Page
See Also:
Page.createControl(org.eclipse.swt.widgets.Composite)

createPaletteRoot

protected abstract MuvitorPaletteRoot createPaletteRoot()
Subclasses must implement to specify the PaletteRoot that should be used by this page's EditDomain and which defines the contents of the palette.

Use a MuvitorPaletteRoot for convenience.

Returns:
The MuvitorPaletteRoot for the EditDomain of this page.

getThumbSashWeights

protected int[] getThumbSashWeights()
The two values in the returned array specify how the fly-out composite's space is being divided between the palette entries and the thumbnail in the palette. When implementing, this template should be used:
return new int[] { Palette_Weight, Thumb_Weight }; The pair (3,1) is a good default value, but you may override this method.

Returns:
An array of 2 integers describing the ratio of the palette to the thumbnail.

getSharedKeyHandler

protected final KeyHandler getSharedKeyHandler()
Configures the keyHandler with standard key strokes like DEL (for DeleteAction) and F2 (for direct edit).

Returns:
A lazily created shared KeyHandler for the viewers on this page.
See Also:
setupKeyHandler(KeyHandler)

getNumberOfViewers

public final int getNumberOfViewers()
Returns:
The number of viewers that are hosted on this page.
See Also:
getViewerContents(), createGraphicalViewerComposite()

getCurrentViewer

public final MuvitorPage.MultiViewerPageViewer getCurrentViewer()
Returns:
The current viewer of this page
See Also:
setCurrentViewer(MultiViewerPageViewer)

getViewerContents

protected abstract EObject[] getViewerContents()
The viewer's are arranged horizontally and will be showing these objects in the order of the returned array from left to right. The length of the array determines the value of getNumberOfViewers()!

Returns:
The objects that will be set as contents in each of viewers.
See Also:
setViewersContents(int, EObject), createGraphicalViewerComposite()

getViewersContents

public final EObject getViewersContents(int viewerPosition)
A method to access the object which is being displayed in a specific viewer.

Parameters:
viewerPosition - the position (starting with 0) of the viewer
Returns:
the model of the top edit part of viewers[viewerPosition]
See Also:
setViewersContents(int, EObject)

getViewer

public final GraphicalViewer getViewer(EObject forModel)
Description copied from interface: IGraphicalViewerProvider
Method to get the viewer showing a specific model. Added to support AnimatingCommand in finding the viewer in which it should animate some figures.

A sample implementation could look like this:

 public GraphicalViewer getViewer(final EObject model) {
        for (final GraphicalViewer viewer : viewers) {
                if (viewer.getContents() != null
                                && viewer.getContents().getModel() == model) {
                        return viewer;
                }
        }
        return null;
 }
 

Specified by:
getViewer in interface IGraphicalViewerProvider
Parameters:
forModel - the model element shown in the viewer
Returns:
a viewer showing the passed model if it exists, otherwise null

setViewersContents

public final void setViewersContents(int viewerPosition,
                                     EObject model)
A method to set a new object to be shown in a specific viewer.

Parameters:
viewerPosition - the position (starting with 0) of the viewer
See Also:
getViewerContents()

setViewerVisibility

public final void setViewerVisibility(int viewerPosition,
                                      boolean visible)
This method sets the visibility of a viewer's control and relayouts the SashForm so that the visible viewers on it occupy the remaining space.

Parameters:
viewerPosition - the position (starting with 0) of the viewer

setupKeyHandler

protected abstract void setupKeyHandler(KeyHandler kh)
Subclasses must implement to associate KeyStrokes with Actions in the passed KeyHandler which is the one used for the GraphicalViewers.

May be left empty.

See Also:
createControl(Composite)

createContextMenuProvider

protected abstract ContextMenuProviderWithActionRegistry createContextMenuProvider(EditPartViewer viewer)
Subclasses must implement to specify the ContextMenuProviderWithActionRegistry that should be used by this page's GraphicalViewers and is responsible to show the created actions in the context menu.

Parameters:
viewer - The graphical viewer for context menu provider
Returns:
The ContextMenuProviderWithActionRegistry for the specified GraphicalViewer.
See Also:
createGraphicalViewerComposite()

createEditPartFactory

protected abstract EditPartFactory createEditPartFactory()
Subclasses must implement to specify the EditPartFactory that should be used by this page's GraphicalViewers.

Returns:
The EditPartFactory for the GraphicalViewers of this page.
See Also:
createGraphicalViewerComposite()

dispose

public void dispose()
Stops listening to the model, removes viewers from the #editor's SelectionSynchronizer, stops listening to the global selection service, and deactivates the thumbnail.

May be extended by subclasses to perform further cleaning up for initializations done in init(IPageSite) but super implementation must be called!

Specified by:
dispose in interface IPage
Overrides:
dispose in class Page

getControl

public final Control getControl()
Specified by:
getControl in interface IPage
Specified by:
getControl in class Page

setFocus

public final void setFocus()
Sets focus to a part in the page.

Specified by:
setFocus in interface IPage
Specified by:
setFocus in class Page

selectionChanged

public final void selectionChanged(IWorkbenchPart part,
                                   ISelection selection)
If a selection change occurs in the one of the editor components (possibly in the current viewer) the UpdateActions in this page's ActionRegistry are being updated.

Specified by:
selectionChanged in interface ISelectionListener

updateActions

protected final void updateActions()
Updates all UpdateActions registered in the actionRegistry.


getAdapter

public Object getAdapter(Class clazz)
Extended to provide zoomManagerDelegate as ZoomManager. Subclasses may extend further, but must call super implementation!

Specified by:
getAdapter in interface IAdaptable

getActionRegistry

protected final ActionRegistry getActionRegistry()
Returns:
the actionRegistry

getEditor

public final MuvitorTreeEditor getEditor()
Returns:
the parent editor

setCurrentViewer

protected final void setCurrentViewer(MuvitorPage.MultiViewerPageViewer viewer)
This method sets the current graphical viewer of this page which implies that the passed viewer

Parameters:
viewer -

getViewers

protected final List<MuvitorPage.MultiViewerPageViewer> getViewers()
Method to get the list of viewers if needed to implement advanced editor features. This list is unmodifiable.

To set new contents for a viewer setViewersContents(int, EObject) should be used!

Returns:
the viewers
See Also:
setViewersContents(int, EObject)

getStatusLineManager

public final IStatusLineManager getStatusLineManager()
This can be used to display messages in this page's status line.

Returns:
The IStatusLineManager from the IActionBars of this page's IPageSite

getToolBarManager

public final IToolBarManager getToolBarManager()
This can be used to add actions to this page's tool bar.

Returns:
The IToolBarManager from the IActionBars of this page's IPageSite

commandStackChanged

public final void commandStackChanged(EventObject event)
If some command manipulates the model and is put to the command stack the actions are updated. Remember that the command stack is shared with the parent MuvitorTreeEditor!

Specified by:
commandStackChanged in interface CommandStackListener

notifyChanged

protected void notifyChanged(Notification msg)
By default, an Adapter will be registered with this page's model that passes notifications to this method, which subclasses are expected to override.