Motivation

They Layer view is focused on showing the user draw order; we want a Legend view that focuses on the information the user is presenting using their map.

Inspiration

Our inspiration is a normal paper map "Key"; showing the layers of interest and symbols and categories as needed.

• http://www.kidsgeo.com/geography-for-kids/0027-map-key-and-scale.php

Proposal

The Legend View will be a modified Layer View that has folders to group layers; and where layers can be opened up to show the categories of information they display (for example when theming).

We would also like Legend view to be able to quickly "show and hide" book keeping layers such as "background" layers and "map decorators" which are used to draw the map but are not the key information being communicated.

Example:

• Layer folders may be organised by subject matter; or by content type.
• When theming by an attribute; the categories of attribute data can be displayed with their associated colour or symbol.
• When a smooth gradient is displayed we show a smooth gradient with key values marked such as min, max and median.
  

  Screen mock-ups (view as slideshow)
  	Original Layer View		Legend view is similar		Filter map decorators
  	Filter background layers		Group into folders		Show categories rendered from style

  PDF Mockup: LegendView.pdf
  

Outline:

• We will update our core Map/Layer EMF model. Paul will be using his recent Eclipse Modelling Framework experience on this one.
  • IFolder - used to group layers
  • ICategory - generated from Style (either from Rules or from categorisation or interpolate functions)
• Legend support classes will require
  • Control of Display Name
  • Control of Icon used
  • Show / Hide in Legend
• Layer order will be similar to power point (move forward, move backward, move to front, move to back buttons).
  • Layer order buttons will respect "natural" ordering (raster, polygon, line, point) so "move to back" on a point layer will place it just in front of the first line layer.
  • Display order will be handled by enabling users to select a layer and move up and down in the map display (and Layer view) but not changing the order in the Legend View.
• All legend items can be shown/hidden from the legend
  • Shortcut - Hide/Show Mapgraphic toggle in the legend view toolbar to filter all map graphics in one go
  • Shortcut - Hide/Show Background toggle in the legend view toolbar to filter all background layers in one go
• Consider
  • Grid toggle for legend view toolbar (would need to add a grid to the map if not already present)

Status

Project Steering committee support:

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

Committer Support:

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

Documentation

• Legend View reference page
• Using the Legend View Tasks page

Tasks

A list of the tasks needed to accomplish this change; if you prefer you can use a single Jira issue with subtasks. It is important to include any deadlines so the community knows when you are working to a schedule.

	no progress		in progress		blocked		help needed		done

Quick definition of LegendView based on Layer list:

1. NZ: Introduce Naz to udig-devel (hi Naz!)
   • NZ: Review RFC and ask questions
   • JG: Hunt down wireframe diagram
2. NZ: Send to community for review and feedback
3. PP: Paul will update the EMF module with Legend support classed (icon, display name, show/hide in legend) 
   • ILayer
   • IFolder
   • ICategory
4. NZ: initial Legend View
   • Straight up copy of Layers view
   • Toggle filtering based on layer type (MapGraphics toggle/Background layers)
5. CHECKPOINT: Commit and pull request
   • https://github.com/uDig/udig-platform/pull/101

Making LegendView working against LegendItemList:

1. Migrate to LegendItemList (that paul created above)
   • Migrate content provider over to Map Legend Item List (it will be empty)
   • Note ICategory is created from SLD and not subject to AddLayerCommand
2. Create AddFolderItemCommand (call from view menu?)
3. Create AddLayerItemCommand (call from view menu?
   • Create AddLayerItemCommand by copying AddLayerCommand as starting point
   • Aside: Quick Hack if you want to see something - update AddLayerItemCommand to add the Layer to both lists (you would need to copy the layer as it can only belong in one list)
4. Create drag/drop action to control moving layers in and out of folders
5. QA Check and initial Home user docs
   • Reference Legend View
   • Tasks Page Using the Legend View
6. CHECKPOINT: Commit an pull request

Render Integration (team effort):

1. Now that it works we can hook it up to the rendering engine
   • Warn the udig-devel email list; schedule the work for a friday/saturday in order not to distrupt development
   • Remove ContextModel Layer List
   • Update Map getLayerList() method to traverse the legend items and produce a list sorted by zorder. [Update] A separate list map.getLayers() was created to cater this requirement.
   • Regenerate MapItemProvider thru EMF
     • Create separate MapLayersItemProvider for LayersView and
     • Create separate MapLegendItemProvider for LegendView
   • Create a LegendLayerItem, which contains a reference to the actual Layer
     • Update LegendItems list to refer to this new object
2. RenderManager and friends may need to check getLayerList method above; but their event handling code will need to change over to legend item list (rather than ContextModel).
   • Analyze impact of migrating listeners and actions from LayersView to LegendView (considering the new data model and new display)
   • Migrate (copy from LayersView) all listeners of map-related events
   • Migrate (copy from LayersView) all actions/functionalities
   • Update sorting functions to refer to new layers list
   • Update toggle filtering functions to refer to LegendItem list
   • Update LegendView drag-drop functionality to restrict to LegendView items only
3. LayerView will need to fixed up as well; should be a matter of changing where it listens to events
4. Naz to ask for commit access for the uDig legend branch
5. Naz to read and learn about EMF stuff
6. CHECKPOINT: Commit and pull request

Process style into categories for the complete legend experience:

1. Introduce ICategory
2. Generate from Style to a category data model stored on the layer blackboard
   • Listen to SLD change; and trigger code to review the style and generate out category data model
3. Update the Legend Content Providder to check for category information on the layer blackbaord
   • Update LabelProviders and so on to correctly display the category information
4. Update user guide documentation
   • Reference Legend View
   • Tasks Page Using the Legend View
5. CHECKPOINT: Commit and pull request

Status:

• UDIG-1883 Legend View
• UDIG-1884 Legend Support Classes