Eclipse插件开发：GEF入门系列宝典

An event will be fired immediately if the new * state is different than the current one. * * @param dirty the new dirty state to set */ protected void setDirty(boolean dirty) { if(isDirty != dirty) { isDirty = dirty; firePropertyChange(IEditorPart.PROP_DIRTY); } } Now we implement the listener and attach it to the CommandStack as shown in Example 3-5. Example 3-5: The CommandStackListener /** * The CommandStackListener that listens for * CommandStack changes. */ private CommandStackListener commandStackListener = new CommandStackListener() { public void commandStackChanged(EventObject event) { setDirty(getCommandStack().isDirty()); } }; /** * Returns the CommandStack of this editor's * EditDomain. * * @return the CommandStack */ public CommandStack getCommandStack() { return getEditDomain().getCommandStack(); } /** * Returns the CommandStackListener. * @return the CommandStackListener */ protected CommandStackListener getCommandStackListener() { return commandStackListener; } Attaching the listener should be done when the editor gets it input, and removing it should be done in the editor's dispose method. See Example 3-6. Example 3-6: Attaching and removing the CommandStackListener /** * Initializes the editor. * @see EditorPart#init */ public void init(IEditorSite site, IEditorInput input) throws PartInitException { // store site and input setSite(site); setInput(input); // add CommandStackListener getCommandStack().addCommandStackListener(getCommandStackListener()); } /* (non-Javadoc) * @see org.eclipse.ui.IWorkbenchPart#dispose() */ public void dispose() { // remove CommandStackListener getCommandStack().removeCommandStackListener(getCommandStackListener( )); // important: always call super implementation of dispose super.dispose(); } Do not forget to update the CommandStack when the editor content is saved. See Example 3-7. Example 3-7: Update CommandStack on editor save /** * TODO: Implement "doSave". * @see EditorPart#doSave */ public void doSave(IProgressMonitor monitor) { // your implementation here // update CommandStack getCommandStack().markSaveLocation(); } /** * TODO: Implement "doSaveAs". * @see EditorPart#doSaveAs */ public void doSaveAs() { // your implementation here // update CommandStack getCommandStack().markSaveLocation(); } 3.4.4 Attaching the viewer The GraphicalViewer is the next element that must be integrated into our editor. The method createPartControl is the best location to do this. First we create a GraphicalViewer, then we configure this instance, and add it to the EditDomain. See Example 3-8. Example 3-8: Attaching a GraphicalViewer to our editor /** the graphical viewer */ private GraphicalViewer graphicalViewer; /** * Creates the controls of the editor. * @see EditorPart#createPartControl */ public void createPartControl(Composite parent) { graphicalViewer = createGraphicalViewer(parent); } /** * Creates a new GraphicalViewer, configures, registers * and initializes it. * * @param parent the parent composite * @return a new GraphicalViewer */ private GraphicalViewer createGraphicalViewer(Composite parent) { // create graphical viewer GraphicalViewer viewer = new ScrollingGraphicalViewer(); viewer.createControl(parent); // configure the viewer viewer.getControl().setBackground(parent.getBackground()); viewer.setRootEditPart(new ScalableFreeformRootEditPart()); // hook the viewer into the EditDomain getEditDomain().addViewer(viewer); // acticate the viewer as selection provider for Eclipse getSite().setSelectionProvider(viewer); // initialize the viewer with input viewer.setEditPartFactory(getEditPartFactory()); viewer.setContents(getContent()); return viewer; } /** * Returns the GraphicalViewer of this editor. * @return the GraphicalViewer */ public GraphicalViewer getGraphicalViewer() { return graphicalViewer; } /** * Returns the content of this editor * @return the model object */ protected Object getContent() { // todo return your model here return null; } /** * Returns the EditPartFactory that the * GraphicalViewer will use. * @return the EditPartFactory */ protected EditPartFactory getEditPartFactory() { // todo return your EditPartFactory here return null; } Note Although we have chosen to use the ScalableFreeformRootEditPart here, you are free to use whatever RootEditPart you like. 3.4.5 Being adaptable One of the key concepts inside Eclipse is the IAdaptable technology. It is also used within the Graphical Editing Framework. That is why we have to ensure that our editor implements this interface so that the GEF elements we have created provide adaptable behavior, which may be of interest to the Graphical Editing Framework itself or to other Eclipse code. So far, we have created the following important GEF elements: , EditDomain , GraphicalViewer EditDomain also provides access to a third important element, CommandStack. Example 3-9 shows how to provide adapter access to the elements in our sample editor. Example 3-9: Overwriting the getAdapter method /* (non-Javadoc) * @see org.eclipse.core.runtime.IAdaptable#getAdapter(java.lang.Class) */ public Object getAdapter(Class adapter) { // we need to handle common GEF elements we created if (adapter == GraphicalViewer.class || adapter == EditPartViewer.class) return getGraphicalViewer(); else if (adapter == CommandStack.class) return getCommandStack(); else if (adapter == EditDomain.class) return getEditDomain(); // the super implementation handles the rest return super.getAdapter(adapter); } 3.4.6 Introducing the palette The palette in GEF editors is the home for tools. But before we discuss tools, we need to create a palette inside our editor. The GEF palette is implemented reusing GEF technology; thus it has a model presented in a viewer (the PaletteViewer). The palette model The palette model is a simple model starting with a PaletteRoot. Each PaletteViewer needs a PaletteRoot. The PaletteRoot is a palette container (PaletteContainer). Palette containers are used to organize palette entries (PaletteEntry). Besides the PaletteRoot, there are two additional palette containers - PaletteGroup and PaletteDrawer. We suggest that you use both of them to organize your palette. Each provides a container for palette entries, but the PaletteGroup cannot be collapsed, while the PaletteDrawer can be collapsed. Additional information can be found in the GEF JavaDoc. Attaching the palette Attaching a palette is similar to attaching a viewer. First, we need to create a new PaletteViewer, as shown in Example 3-10. Example 3-10: Creating a PaletteViewer /** * Creates a new PaletteViewer, configures, registers * and initializes it. * @param parent the parent composite * @return a new PaletteViewer */ private PaletteViewer createPaletteViewer(Composite parent) { // create graphical viewer PaletteViewer viewer = new PaletteViewer(); viewer.createControl(parent); // hook the viewer into the EditDomain (only one palette per EditDomain) getEditDomain().setPaletteViewer(viewer); // important: the palette is initialized via EditDomain getEditDomain().setPaletteRoot(getPaletteRoot()); return viewer; } /** * Returns the PaletteRoot this editor's palette uses. * @return the PaletteRoot */ protected PaletteRoot getPaletteRoot() { // todo add your palette entries here return null; } Next, we need to add this viewer to the editor's composite. The SWT SashForm is used to have the palette's width modifiable, as shown in Example 3-11. Example 3-11: Adding the PaletteViewer to the editor's composite /** * Creates the controls of the editor. * @see EditorPart#createPartControl */ public void createPartControl(Composite parent) { SashForm sashForm = new SashForm(parent, SWT.HORIZONTAL); sashForm.setWeights(new int[] {30,70}); paletteViewer = createPaletteViewer(sashForm); graphicalViewer = createGraphicalViewer(sashForm); } /** the palette viewer */ private PaletteViewer paletteViewer; /** * Returns the PaletteViewer of this editor. * @return the PaletteViewer */ public PaletteViewer getPaletteViewer() { return paletteViewer; } There are several default tools available, and we need to add them so that we have an initial PaletteRoot. See Example 3-12. Example 3-12: Initial PaletteRoot with default tools /** the palette root */ private PaletteRoot paletteRoot; /** * Returns the PaletteRoot this editor's palette uses. * @return the PaletteRoot */ protected PaletteRoot getPaletteRoot() { if (null == paletteRoot) { // create root paletteRoot = new PaletteRoot(); List categories = new ArrayList(); // a group of default control tools PaletteGroup controls = new PaletteGroup("Controls"); // the selection tool ToolEntry tool = new SelectionToolEntry(); controls.add(tool); // use selection tool as default entry paletteRoot.setDefaultEntry(tool); // the marquee selection tool controls.add(new MarqueeToolEntry()); // a separator PaletteSeparator separator = new PaletteSeparator( EditorExamplePlugin.PLUGIN_ID + ".palette.seperator"); separator.setUserModificationPermission( PaletteEntry.PERMISSION_NO_MODIFICATION); controls.add(separator); // a tool for creating connection controls.add( new ConnectionCreationToolEntry( "Connections", "Create Connections", null, ImageDescriptor.createFromFile( getClass(), "icons/connection16.gif"), ImageDescriptor.createFromFile( getClass(), "icons/connection24.gif"))); // todo add your palette drawers and entries here // add all categroies to root paletteRoot.addAll(categories); } return paletteRoot; } Palette customizer It is possible to attach a palette customizer to the palette. This will enable the users of your editor to modify the palette to work in the way they prefer. For implementation details, please see our completed redbook sample application as described in Chapter 7, "Implementing the sample" on page 203, or the Logic example application provided from the GEF development team. 3.4.7 Actions Actions are common objects in the Eclipse workbench to do something when user requests are initiated through menu items, toolbar buttons or context menu items. The Graphical Editing Framework provides a set of standard actions and an infrastructure for using these actions within the Graphical Editing Framework. ActionRegistry The class org.eclipse.gef.actions.ActionRegistry serves as a container for editor actions. The editor is responsible for providing and maintaining an ActionRegistry. See Example 3-13. Example 3-13: Adding an ActionRegistry to the editor /** the editor's action registry */ private ActionRegistry actionRegistry; /** * Returns the action registry of this editor. * @return the action registry */ public ActionRegistry getActionRegistry() { if (actionRegistry == null) actionRegistry = new ActionRegistry(); return actionRegistry; } /* (non-Javadoc) * @see org.eclipse.core.runtime.IAdaptable#getAdapter(java.lang.Class) */ public Object getAdapter(Class adapter) { // we need to handle common GEF elements we created if (adapter == GraphicalViewer.class || adapter == EditPartViewer.class) return getGraphicalViewer(); else if (adapter == CommandStack.class) return getCommandStack(); else if (adapter == EditDomain.class) return getEditDomain(); else if (adapter == ActionRegistry.class) return getActionRegistry(); // the super implementation handles the rest return super.getAdapter(adapter); } /* (non-Javadoc) * @see org.eclipse.ui.IWorkbenchPart#dispose() */ public void dispose() { // remove CommandStackListener getCommandStack().removeCommandStackListener(getCommandStackListener()); // disposy the ActionRegistry (will dispose all actions) getActionRegistry().dispose(); // important: always call super implementation of dispose super.dispose(); } Managing actions As soon as we have the ActionRegistry, we are able to create actions and to register them. The Graphical Editing Framework provides a set of default actions (redo, undo, delete, print, and save). These actions need some special handling to stay up-to-date with the editor, the CommandStack or the EditParts. The GEF default actions are not implemented as listeners to some events. Instead, they have to be updated manually. This can be done from within the editor as shown in Example 3-14. Example 3-14: Added infrastructure for supporting different actions /** the list of action ids that are to EditPart actions */ private List editPartActionIDs = new ArrayList(); /** the list of action ids that are to CommandStack actions */ private List stackActionIDs = new ArrayList(); /** the list of action ids that are editor actions */ private List editorActionIDs = new ArrayList(); /** * Adds an EditPart action to this editor. * *

EditPart actions are actions that depend * and work on the selected EditParts. * * @param action the EditPart action */ protected void addEditPartAction(SelectionAction action) { getActionRegistry().registerAction(action); editPartActionIDs.add(action.getId()); } /** * Adds an CommandStack action to this editor. * *

CommandStack actions are actions that depend * and work on the CommandStack. * * @param action the CommandStack action */ protected void addStackAction(StackAction action) { getActionRegistry().registerAction(action); stackActionIDs.add(action.getId()); } /** * Adds an editor action to this editor. * *

ActionRegistry. * (This is a helper method.) * * @param action the action to add. */ protected void addAction(IAction action) { getActionRegistry().registerAction(action); } Now that we have the action infrastructure, we must implement the automatic updating of the different actions. Editor actions must be updated when the editor changes, CommandStack actions when the CommandStack changes, and EditPart actions when the selection changes. Example 3-15 shows how to add update support for actions to our sample editor. Example 3-15: Adding update support for the actions /** * Updates the specified actions. * * @param actionIds the list of ids of actions to update */ private void updateActions(List actionIds) { for (Iterator ids = actionIds.iterator(); ids.hasNext();) { IAction action = getActionRegistry().getAction(ids.next()); if (null != action && action instanceof UpdateAction) ((UpdateAction) action).update(); } } /** * The CommandStackListener that listens for * CommandStack changes. */ private CommandStackListener commandStackListener = new CommandStackListener() { public void commandStackChanged(EventObject event) { updateActions(stackActionIDs); setDirty(getCommandStack().isDirty()); } }; /** the selection listener */ private ISelectionListener selectionListener = new ISelectionListener() { public void selectionChanged(IWorkbenchPart part, ISelection selection) { updateActions(editPartActionIDs); } }; /** * Returns the selection listener. * * @return the ISelectionListener */ protected ISelectionListener getSelectionListener() { return selectionListener; } /** * Initializes the editor. * @see EditorPart#init */ public void init(IEditorSite site, IEditorInput input) throws PartInitException { // store site and input setSite(site); setInput(input); // add CommandStackListener getCommandStack().addCommandStackListener(getCommandStackListener()); // add selection change listener getSite() .getWorkbenchWindow() .getSelectionService() .addSelectionListener( getSelectionListener()); } /* (non-Javadoc) * @see org.eclipse.ui.IWorkbenchPart#dispose() */ public void dispose() { // remove CommandStackListener getCommandStack().removeCommandStackListener(getCommandStackListener( )); // remove selection listener getSite() .getWorkbenchWindow() .getSelectionService() .removeSelectionListener( getSelectionListener()); / disposy the ActionRegistry (will dispose all actions) getActionRegistry().dispose(); // important: always call super implementation of dispose super.dispose(); } /* (non-Javadoc) * @see org.eclipse.ui.part.WorkbenchPart#firePropertyChange(int) */ protected void firePropertyChange(int propertyId) { super.firePropertyChange(propertyId); updateActions(editorActionIDs); } Now, when all the infrastructure is ready, we are able to create and add our actions as shown in Example 3-16. Example 3-16: Adding actions to the editor /** * Initializes the editor. * @see EditorPart#init */ public void init(IEditorSite site, IEditorInput input) throws PartInitException { // store site and input setSite(site); setInput(input); // add CommandStackListener getCommandStack().addCommandStackListener(getCommandStackListener()); // add selection change listener getSite() .getWorkbenchWindow() .getSelectionService() .addSelectionListener( getSelectionListener()); // initialize actions createActions(); } /** * Creates actions and registers them to the ActionRegistry. */ protected void createActions() { addStackAction(new UndoAction(this)); addStackAction(new RedoAction(this)); addEditPartAction(new DeleteAction((IWorkbenchPart) this)); addEditorAction(new SaveAction(this)); addEditorAction(new PrintAction(this)); } 3.4.8 Adapting to the properties view EditParts are responsible for delivering IPropertySource adapters for the properties view, but this is not discussed here. The Graphical Editing Framework provides a solution to cover modifications occurred in the properties view into the CommandStack. This enables the possibility to undo and redo changes. To enable this, the editor must deliver its own IPropertySheetPage. This IPropertySheetPage is a default PropertySheetPage customized with an undoable root entry provided by GEF. See Example 3-17. Example 3-17: Making the properties view undoable /* (non-Javadoc) * @see org.eclipse.core.runtime.IAdaptable#getAdapter(java.lang.Class) */ public Object getAdapter(Class adapter) { // we need to handle common GEF elements we created if (adapter == GraphicalViewer.class || adapter == EditPartViewer.class) return getGraphicalViewer(); else if (adapter == CommandStack.class) return getCommandStack(); else if (adapter == EditDomain.class) return getEditDomain(); else if (adapter == ActionRegistry.class) return getActionRegistry(); else if (adapter == IPropertySheetPage.class) return getPropertySheetPage(); // the super implementation handles the rest return super.getAdapter(adapter); } /** the undoable IPropertySheetPage */ private PropertySheetPage undoablePropertySheetPage; /** * Returns the undoable PropertySheetPage for * this editor. * * @return the undoable PropertySheetPage */ protected PropertySheetPage getPropertySheetPage() { if (null == undoablePropertySheetPage) { undoablePropertySheetPage = new PropertySheetPage(); undoablePropertySheetPage.setRootEntry( GEFPlugin.createUndoablePropertySheetEntry(getCommandStack())); } return undoablePropertySheetPage; } 3.4.9 Providing an outline view Providing an outline view is handled in the typical Eclipse way. We need to provide an adapter of type IContentOutlinePage. We can do this in several ways. One way is to create a complete SWT based outline view without using the Graphical Editing Framework. In many cases this is suitable and can be easily done, because many components, such as content and label providers or even tree viewers, can be reused to show a tree of your model objects. If you do not have these reusable components available, then a second way is to build a tree with GEF components. The Graphical Editing Framework provides a TreeViewer and TreeEditParts for this case. You can also reuse actions created for your graphical editor. For details about implementing a model tree with the GEF TreeViewer and TreeEditParts, please see our redbook sample application. A third way is to provide an overview of your graphical editor. Example 3-18 and Example 3-19 show a possible implementation of this. Example 3-18: An overview outline page /** * This is a sample implementation of an outline page showing an * overview of a graphical editor. * * @author Gunnar Wagenknecht */ public class OverviewOutlinePage extends Page implements IContentOutlinePage { /** the control of the overview */ private Canvas overview; /** the root edit part */ private ScalableFreeformRootEditPart rootEditPart; /** the thumbnail */ private Thumbnail thumbnail; / ** * Creates a new OverviewOutlinePage instance. * @param rootEditPart the root edit part to show the overview from */ public OverviewOutlinePage(ScalableFreeformRootEditPart rootEditPart) { super(); this.rootEditPart = rootEditPart; } /* (non-Javadoc) * @see ISelectionProvider#addSelectionChangedListener * (ISelectionChangedListener) */ public void addSelectionChangedListener(ISelectionChangedListener listener) {} /* (non-Javadoc) * @see IPage#createControl(Composite) */ public void createControl(Composite parent) { // create canvas and lws overview = new Canvas(parent, SWT.NONE); LightweightSystem lws = new LightweightSystem(overview); // create thumbnail thumbnail = new ScrollableThumbnail((Viewport) rootEditPart.getFigure()); thumbnail.setBorder(new MarginBorder(3)); thumbnail.setSource( rootEditPart.getLayer(LayerConstants.PRINTABLE_LAYERS)); lws.setContents(thumbnail); } /* (non-Javadoc) * @see org.eclipse.ui.part.IPage#dispose() */ public void dispose() { if (null != thumbnail) thumbnail.deactivate(); super.dispose(); } /* (non-Javadoc) * @see org.eclipse.ui.part.IPage#getControl() */ public Control getControl() { return overview; } /* (non-Javadoc) * @see org.eclipse.jface.viewers.ISelectionProvider#getSelection() */ public ISelection getSelection() { return StructuredSelection.EMPTY; } /* (non-Javadoc) * @see ISelectionProvider#removeSelectionChangedListener * (ISelectionChangedListener) */ public void removeSelectionChangedListener( ISelectionChangedListener listener) {} /* (non-Javadoc) * @see org.eclipse.ui.part.IPage#setFocus() */ public void setFocus() { if (getControl() != null) getControl().setFocus(); } /* (non-Javadoc) * @see ISelectionProvider#setSelection(ISelection) */ public void setSelection(ISelection selection) {} } Example 3-19: Attaching the overview to the editor /* (non-Javadoc) * @see org.eclipse.core.runtime.IAdaptable#getAdapter(java.lang.Class) */ public Object getAdapter(Class adapter) { // we need to handle common GEF elements we created if (adapter == GraphicalViewer.class || adapter == EditPartViewer.class) return getGraphicalViewer(); else if (adapter == CommandStack.class) return getCommandStack(); else if (adapter == EditDomain.class) return getEditDomain(); else if (adapter == ActionRegistry.class) return getActionRegistry(); else if (adapter == IPropertySheetPage.class) return getPropertySheetPage(); else if (adapter == IContentOutlinePage.class) return getOverviewOutlinePage(); // the super implementation handles the rest return super.getAdapter(adapter); } /** the overview outline page */ private OverviewOutlinePage overviewOutlinePage; /** * Returns the overview for the outline view. * * @return the overview */ protected OverviewOutlinePage getOverviewOutlinePage() { if (null == overviewOutlinePage && null != getGraphicalViewer()) { RootEditPart rootEditPart = getGraphicalViewer().getRootEditPart(); if (rootEditPart instanceof ScalableFreeformRootEditPart) { overviewOutlinePage = new OverviewOutlinePage( (ScalableFreeformRootEditPart) rootEditPart); } } return overviewOutlinePage; } Now this page can be used in the editor, as shown in Example 3-19. 3.4.10 Controlling your editor with the keyboard The Graphical Editing Framework uses the concept of KeyHandlers to answer key strokes. By default, the anGEF GraphicalViewer does not answer key strokes. We have to enable this. This is not a difficult task, because as with all other GEF concepts, there is a default implementation available, which provides a very feature-rich set of keys for interacting with a GraphicalViewer. The default implementation is the class org.eclipse.gef.ui.parts.GraphicalViewerKeyHandler. Example 3-20 shows how to use this key handler with our editor sample. Example 3-20: Enabling our editor for keyboard interaction /** * Creates a new GraphicalViewer, configures, registers * and initializes it. * @param parent the parent composite * @return a new GraphicalViewer */ private GraphicalViewer createGraphicalViewer(Composite parent) { // create graphical viewer GraphicalViewer viewer = new ScrollingGraphicalViewer(); viewer.createControl(parent); // configure the viewer viewer.getControl().setBackground(parent.getBackground()); viewer.setRootEditPart(new ScalableFreeformRootEditPart()); viewer.setKeyHandler(new GraphicalViewerKeyHandler(viewer)); // hook the viewer into the EditDomain getEditDomain().addViewer(viewer); // acticate the viewer as selection provider for Eclipse getSite().setSelectionProvider(viewer); // initialize the viewer with input viewer.setEditPartFactory(getEditPartFactory()); viewer.setContents(getContent()); return viewer; } Tip If you like to attach actions to your own key strokes, you do not need to overwrite the GraphicalViewerKeyHandler. It is simply possible to attach a parent to KeyHandlers. Thus, you simply create your own KeyHandler instance (not GraphicalViewerKeyHandler), configure this KeyHandler instance, and set it as the parent of the GraphicalViewerKeyHandler you created for the GraphicalViewer.