Dashboard > uDig > Home > RFC > 1.3 > Use GEF Tool Palette
Use GEF Tool Palette
Added by Levi Putna , last edited by Jody Garnett on Nov 23, 2011  (view change)

Direction of Proposal

*Motivation*: The current system for adding map tools to the tool bar douse not scale well and ends up with a messy end user experience:

  • Tool icons are often confusing
  • Users are forced to hover over several tools displaying the tool tip before they find the tool they are looking for
  • scalability: keyboard shortcuts is handled well; with a key assigned to each category (allowing users to cycle trough editing tools)
  • scalability: Tool drop downs (for each tool category) hides tools from casual discovery; once you click a drop down you can read the tool names
  • scalability: Placing additional tools into the view toolbar gives people two places to look to determine the active tool (example the table view has a ToolAction allowing the selection tool to be chosen)

Finally: our tool drop downs is some of our own custom code we are having to maintain; the eclipse *Graphical Editing Project* has come out with a standard across applications known as the palette.

We would like to adopt the *GEF* Tool Palette for uDig.

The Plan

So the plan:

1. Allow MapEditor to publish a palette
2. Use ApplicationGIS.getToolManager() to obtain the details on all tools
3. Make a PaletteContainer for each ToolCategory
4. ToolEntry for ModalTool
5. Not sure how to handle ActiveTool (zoom in, zoom out - fire and forget tools). I think Palette allows these at the top? or perhaps keep in toolbar...
6. To activate a tool in the palette to work with you simply click on it in the tool.
7. For easy access and sorting tools are stacked in groups of tools, a grouping folder is used to indicate a group of tools with common functionality, groups can be expanded and collapsed to make better use of space and hide less commonly used tools out of the way.


Project Steering committee support:

Andrea Antonello: +1
Jesse Eichar: +1
Jody Garnett: +1
Mauricio Pazos: +1

Committer Support:

Kenneth Gulbrands√ły: +1

A vote of -1 requires an alternate suggestion; community members are invited to indicate support/suggestions.


Documentation change to Users Guide (for an accepted change):

And we would need to update the screen snaps in:


Timeframe: August 17th

Status: https://jira.codehaus.org/browse/UDIG-1780

To review during code review.

Ensure the toolmanager API remains consistent specifically:

  1. how to obtain a tool
    • Tool is obtained form the ToolManager in the normal fashion; the Palette Simply as a MapToolEntry. The MapToolEntry.getId() is used as the identifier to look up the tool in the ToolManager (this is made difficult as look up requires category id as well).
  2. How to get the toolbar manager (although a parameter with the workbenchpart can be added)
    • This is unchanged
  3. How to filter out tools from the toolbar manager (unless a migration plan is provided)
    • The tools are filtered out according to normal tool enablement; the palette does not support enablement as a concept; using only visibility
    • There should also be some control based on "contexts" (but perhaps this was reserved for action tools?)
    • The implementation of a disabled look for GEF is a topic of some workarounds on email lists (http://www.eclipsezone.com/eclipse/forums/t47375.html).

The implementation meets the above constraints.


What Works

  • The Palette shows the available tools
  • You can cycle through several appearance by right clicking
  • We have provided one large icon as a reference to see if it is a good idea
  • Only tools that can function are displayed (so if you switch between a raster and a vector layer the palette will update)

What Does not work

  • keyboard short cuts


  • JH: interface wireframe for community review and feedback
  • JH / SH: implementation in *net.refractions.udig.project.ui.editor*
  • Change MapEditor to extend GraphicalEditorWithFlyoutPalette
    • This super class had a few consequences with respect to the handling of MapEditDomain - we may consider copying the code and adapting it to our purpose rather than carry around extra baggage. Currently we have hijacked a couple methods that are supposed to set up a "graphical veiwer" and used them to set up our MapViewer instead.
  • Figure out who is going to own the EditDomain (it should be the class responsible for the "current tool")
    • Initial attempt of asking MapViewer to own the EditDomain did not work due creation lifecycle of MapEditor
    • now MapPart owns a MapEditDomain; and the MapViewer picks it up when MapViewer.init( MapPart ) is called
    • This gives us three classes with responsibility for the current tool at present
  • Update plugin to use our new editor
    • Mark's initial advice was "add don't replace" hence MapEditoryWithPalette
    • This had the consequence of shaking out assumption with respect to use of MapEditor vs MapPart (a good thing to clarify)
    • We still have duplicates to remove from cut and paste code classes (example MapPaletteEditorSite, ... ). These classes are unused and are a mistake.
  • processing the extension point to produce additional tools
    • Initially add all tools
    • Filter tools displayed; we could not figure this now out (need an example)
    • Hook up tool enablement (hooked up to visibility for now)
  • Turn off the MapEditorActionBarContributor ModalTools toolbar contributions (now that palette works)
    • Used a boolean flag so we can turn it on with a preference setting later if needed
    • Turning off these toolbar contributions broke keyboard shortcuts
  • Update keyboard shortcut code
    • We may have to repurpose the commands to hit the ToolManager (currently they hit the toolbar which no longer exists causing errors)
    • Ensure the palette is watching the ToolManager so it can track keyboard induced changes
    • Null Pointer at DeleteGlobalActionSetterActivator.activate and deactivate for all Edit Tools - fix!
    • Null Pointer at ToolCommandHandler.execute when trying to use shortcuts - fix!
  • Change perspective or make palette open automatically with map
    • The GraphicalEditorWithFlyoutPalette super class is supposed to handle this compare to PageEditor for example
    • Hacked the relationship pretty hard with overriding methods; it now works
    • Palette opens up at zero width; may consider presenting a preference of 10% width?
    • nice smooth transition of the palette view is opened
  • Branch into uDig-platform
    • Branch created called gef_palette
  • make default tool pan or zoom, select is not a tool.
    • ToolManager provides the default (i.e. Zoom); we need to ensure the palette is correctly initialised to match
  • Update plugin.xml to make the editor available
    • A bit more fun with cut and paste here
    • Restore the references to map editor in the plugin.xml files; existing projects will use the "ID" of their editor when asked to open
  • JH / SH: Activate/Deactivate on tool change
    • Activate tools
    • Deactivate Tools
  • JG: Tool visibility
    • Based to Tool Enabled State
  • update documentation
    • As per notes above we need to regenerate the screen snaps
    • Should use Natural Earth dataset; Levi has a new data bundle
  • Review of PSC member required (done via pull request)
    • JG: Review pull request (headers, findbugs, etc...)
    • JE: Review tool manager use / abuse
  • SH/JH: Updated user guide documentation
    • Update Reference (Map editor)
    • Update tutorials:
      • Quickstart
      • Walkthrough 1 ( all bar community extension and postgres)
      • Walkthrough 2

Changing Tools

Issues and Discussion:

  • We went looking for where the "current tool" was stored; and could not find the correct location.
    • We found the activeTool as part of MapViewer and decide to place the MapEditDomain there
    • It now appears as if the ToolManager has this responsibility. ToolManager.activeModalToolProxy is a public field that is updated by ToolProxy
    • So we need to change our approach ... but how?
  • changing tools with keyboard short cuts work; but palette is not told
    • I suspect we need to change the workflow so that MapViewer updates its *MapEditDomain* which the palette should be delegating to
    • this involves taking the responsibility away from ToolAction which calls ModalTool.setActive( true )
    • We can preserve the contract of setActive( boolean ) (i.e. register and deregister) but should move this logic from AbstractModalTool to MapViewer.setModalTool( ModalTool )
  • changing tools with the palette does not change the map cursor
    • Tracked this down ToolProxy.setActive( true ) has the logic to update the cursor; but if you call Tool.setActive( true ) directly it only has the logic to take over the listeners.
      if (active){
         String currentCursorID = modalTool.getCursorID();
  • map editor on its own does not
  • introduction of MapEditorWithPalette has forced more code to make use of MapPart (and it is showing the strain as more methods are added to what has to be an interface)

Design Notes and Research

We would like to adopt the *GEF* Tool Palette for uDig:

  • http://www.eclipse.org/gef/
  • http://www.eclipse.org/articles/Article-GEF-diagram-editor/shape.html
  • *PaletteViewerProvider* - this is what we need to implement; grind through our tool extension point and produce a model of some sort:
    • *FlyoutPaletteComposite*
    • *PaletteViewerPage*
    • *PaletteViewer*: can be used to display a palette; you can use this on the side of your editor
    • *PaletteView*: a view with a single PaletteViewer; the view tracks the current workbench Editor and if it supports the

Review of MapPage and PageEditorPaletteFactory:

public static PaletteRoot createPalette() {
        PaletteRoot paletteRoot = new PaletteRoot();
        return paletteRoot;

We need to do something similar but by processing the tools extension point.

  • ProjectUIPlugin used to have the ToolManager class (that would process the tool extension point for you)
  • ToolManager is not stored there anymore; let us find it ....
  • ApplicationGIS.getToolManager() - okay that made sense

Palette Wishlist

Amongst drawing and graphic manipulation applications the pallet is a common way to access tools. Think of the 'Palette' as a box in which you keep a collection of tools. It contains all of the necessary utensils you will need to manipulate your map.

  • Wish: use associated keyboard shortcut to quickly select a tool without having to always use the Palette to select the tool you wish to use.
  • WIsh: where more than one tool shares the same keyboard shortcut, you can cycle through these other tools by holding by pressing the same keyboard shortcut again.
  • Wish: The pallet is not intended to be a full replacement for the tool bar as some "actions" are better suited to the tool bar. e.g Pint and history navigation...
  • Wish: move many of the tools off the current toolbar leaving space for only a few simple single click (i.e. ActionTools) non toggle tools (ModalTools).
  • Wish: Simplify - allow a preference page (or something) to allow users to select what tools they would like to available via the palette, allowing them to define a simple set of tools they commonly work with.

Powered by a free Atlassian Confluence Open Source Project License granted to uDig. Evaluate Confluence today.
Powered by Atlassian Confluence 2.7.1, the Enterprise Wiki. Bug/feature request - Atlassian news - Contact administrators
User-friendly Desktop Internet GIS