###############################################################################
#  Copyright (c) 2012 Tilera Corporation and others.
#  All rights reserved. This program and the accompanying materials
#  are made available under the terms of the Eclipse Public License v1.0
#  which accompanies this distribution, and is available at
#  http://www.eclipse.org/legal/epl-v10.html
# 
#  Contributors:
#     William R. Swanson (Tilera Corporation)
###############################################################################

Visualizer View Framework
=========================
Version: 1.0
Last updated: 1/19/12

Overview
--------

- The Visualizer framework supports the addition of visual (i.e. graphical)
  representations of run/debug launches to the Eclipse workbench.
  It provides interfaces and default implementations to be used by
  integrators in adding their own graphical views to Eclipse.

- The Visualizer framework is an optional feature of CDT.

- The Visualizer framework consists of the following features/plugins:
  - org.eclipse.cdt.visualizer-feature:
    - org.eclipse.cdt.visualizer.core -- non-UI interface and utilities
    - org.eclipse.cdt.visualizer.ui   -- UI classes and utilities

- The Visualizer framework has the following goals:
  - make it easy to present multiple graphical presentations of
    a running/debugging launch, and allow the user to select between them
  - provide a pluggable infrastructure that does not limit an integrator
    to a specific model, event, or graphic "canvas" in creating such presentations
  - provide sufficient default implementations to make creating a new
    custom presentation as simple as possible

- The framework consists of the following set of interfaces and classes:

      ==========================
      | VisualizerView         |
      ==========================
      |  VisualizerViewer      |
      |                        |
      | --------------------   |  ------------------
      | |                  |   |  |                |
      | |  IVisualizer's   | <=== |   IVisualizer  | ===>  (Model Object)
      | |     graphic      |   |  | implementation |
      | |     control      |   |  |                |
      | |                  |   |  ------------------
      | --------------------   |
      |                        |
      ==========================  

  - VisualizerView -- a top-level Eclipse workbench view that
      contains and presents a VisualizerViewer
      
      The VisualizerView also provides support for a toolbar and
      context menu, which can be populated by IVisualizers when
      they are selected.

  - VisualierViewer -- a container control that manages one or more
     IVisualizers and their corresponding graphic controls.
     
     The VisualizerViewer automatically switches between its available
     IVisualizers based on the current workbench selection.
     
     The viewer also mediates between its parent View and child IVisualizers
     on things like:
       - content selection (workbench selection <==> IVisulizer selection)
       - toolbar population and updating
       - context menu events and updating

  - IVisualizer -- an API for a class that encapsulates:
    - a graphic representation of one or more model object types
    - a top-level graphic display control (e.g. an SWT canvas, GEF canvas, etc.)
      that is used to present this graphic representation in the VisualizerViewer

  - the "model" class -- this is not a specific class type,
    it's basically any top-level Object that can be selected and
    used to obtain the state to be presented by an IVisualizer
    (for example, a Launch in the Debug View, or a text selection
     in an editor)

- The framework provides default implementations of VisualizerView,
  and VisualizerViewer, and base classes that can be used to
  create IVisualizer implementations.

- The framework provides an extension point by which IVisualizer implementations
  can be registered. This is read by the default VisualizerViewer,
  and used to populate its initial set of IVisualizer views


Extension Points:
-----------------

The base class VisualizerViewer checks the following extension point
for plugin contributions of IVisualizer implementations:

- org.eclipse.cdt.visualizer.ui.vizualizer
  - id:    unique ID of this visualizer type
  - class: implementation of IVisualizer interface

  Examples:

   <!-- Visualizer declarations -->

   <extension
         point="org.eclipse.cdt.visualizer.ui.visualizer">
         
      <!-- "Grid View" visualizer -->
      <visualizer
            id="com.tilera.ide.views.grid.visualizer"
            class="com.tilera.ide.views.grid.GridViewVisualizer">
      </visualizer>

      <!-- "Test Canvas" visualizer -->
      <visualizer
            id="org.eclipse.cdt.visualizer.ui.test.TestCanvasVisualizer"
            class="org.eclipse.cdt.visualizer.ui.test.TestCanvasVisualizer">
      </visualizer>

   </extension>


Package/Class hierarchy:
------------------------

- feature: org.eclipse.cdt.visualizer

    - plugin: org.eclipse.cdt.visualizer.core

      - org.eclipse.cdt.visualizer.core.plugin

        - CDTVisualizerCorePlugin -- plugin activator class (mainly used to access ResourceManager)

      - org.eclipse.cdt.visualizer.core

        - ResourceManager  -- resource manager, handles strings only (see UIResourceManager below)
        - Extension        -- utility class for dealing with extension points
        - ExtensionElement -- utility class for dealing with extension definitions

    - plugin: org.eclipse.cdt.visualizer.ui
    
      - org.eclipse.cdt.visualizer.ui.plugin

        - CDTVisualizerUIPlugin -- plugin activator class (mainly used for logging and UIResourceManager)

      - org.eclipse.cdt.visualizer.ui

        - VisualizerView    -- base class for top-level Visualizer "view" in Eclipse workbench
	      - handles:
	        - display of single IVisualizerViewer
	        - boilerplate code for workbench views
	        
        - IVisualizerViewer -- visualizer "viewer" container interface
        - VisualizerViewer  -- base class for IVisualizerViewer implementations
	      - handles:
	        - loading and managing a list of IVisualizers
	        - routing of selection
		      - from workbench into current IVisualizer
		      - from current IVisualizer back to workbench
	        - manages viewer toolbar and content menu,
		      asks current IVisualizer to populate these as needed

        - IVisualizer       -- interface for visualizer (graphic representation, like Grid View)
        - Visualizer        -- base class for IVisualizer implementations
	      - handles:
	        - creating and painting a graphic component
	        - management of selection for that component
	        - populating toolbar and context menu content on demand
		      
        - VisualizerAction  -- base class for toolbar/menu actions (convenience wrapper for Action class)

      - org.eclipse.cdt.visualizer.ui.events

        - VisualizerViewerEvent -- event raised by VisualizerViewer (visualizer changed, context menu event)
        - IVisualizerViewerListener -- listener interface for VisualizerViewerEvent listeners

      - org.eclipse.cdt.visualizer.ui.canvas

        - GraphicCanvasVisualizer -- base class for visualizers based on GraphicCanvas component
        - GraphicCanvas     -- simple canvas that paints a list of GraphicObjects
        - IGraphicObject    -- interface for objects to be drawn on GraphicCanvas
        - GraphicObject     -- base class implementation of IGraphicObject
        - BufferedCanvas    -- base class for GraphicCanvas (or any canvas component with back-buffering)

      - org.eclipse.cdt.visualizer.ui.test

        - TestCanvasVisualizer -- IVisualizer wrapper for TestCanvas
        - TestCanvas -- simple canvas example that displays current selection as text

      - org.eclipse.cdt.visualizer.ui.util

		- GUIUtils -- assorted UI utility methods      
        - UIResourceManager -- resource manager, includes strings, images, fonts, colors
        - Colors -- SWT color resource manager, used with UIResourceManager
        - SelectionUtils -- ISelection manipulation utilities
        - SelectionManager -- ISelectionProvider implementation, manages selection for a containing class
        - SelectionProviderAdapter -- ISelectionProvider wrapper for classes that don't implement it
        - ListenerList -- listener manager class
        - Event -- event base class
        - MouseMonitor -- mouse event tracking utility class
        - RunnableWithResult -- Runnable that returns a result
        - Timer -- UI timer class
        - Todo -- work tracking utility class
        - WorkbenchSelectionAdapter -- manages interaction between workbench selection and a specified IViewPart


Creating a Visualizer
---------------------

This is a summary of the steps to take in developing a visualizer.
(For a specific example of this, see the Multicore Debug Visualizer,
defined in the org.eclipse.cdt.dsf.gdb.multicorevisualizer.ui plugin.)

- Add the VisualizerView to the workbench.
  Note: this implicitly creates a VisualizerViewer instance.

  NOTE: This is currently done by the Visualizer framework itself,
  with the following plugin.xml extension markup:

  For example:

   <extension
         point="org.eclipse.ui.views">
      <view
            category="org.eclipse.debug.ui"
            class="org.eclipse.cdt.visualizer.ui.VisualizerView"
            icon="icons/full/view16/visualizer_view.gif"
            id="org.eclipse.cdt.visualizer.view"
            name="%view.visualizer.name">
      </view>
   </extension>
  

- declare your visualizer class via the extension point
  (described below under Extension Points)

   <extension
         point="org.eclipse.cdt.visualizer.ui.visualizer">
      <!-- "Multicore View" visualizer -->
      <visualizer
            id="org.eclipse.cdt.dsf.gdb.multicorevisualizer.visualizer"
            class="org.eclipse.cdt.dsf.gdb.multicorevisualizer.internal.ui.view.MulticoreVisualizer">
      </visualizer>
   </extension>


- Define your IVisualizer class, either:

  - completely from scratch, implementing IVisualizer

  - derived from the Visualizer base class

  - if you want to use the supplied GraphicCanvas as your control,
    use the GraphicCanvasVisualizer base class instead


- Implement the IVisualizer interface:

  - implement getName(), getDisplayName(), and getDescription()
    to provide a UI-visible name and tooltip for your visualizer

  - implement createControl() to return the UI control to be
    displayed for your visualizer in the VisualizerView
    (if you're using the GraphicCanvasVisualizer base class,
     override createCanvas() and initializeCanvas() instead)

  - implement handlesSelection() to determine whether your
     visualizer can display the current selection
     (your visualizer is only selected if it returns a higher
      value from this call than any other visualizer)

  - implement visualizerSelected()/visualizerDeselected()
     to handle any setup/cleanup when your visualizer becomes
     active or inactive

  - implement workbenchSelectionChanged() to handle changes in
     the workbench selection (typically, this means updating the
     visualizer's displayed content, and/or mapping the current
     selection to selected item(s) in the visualizer display)

  - implement the selection-management methods
    (getSelection(), setSelection() and add/removeSelectionChangedListener())
    to handle exposing the visualizer's selection to the workbench
    (typically, these methods can be delegated to an instance of
     the SelectionManager utility class, and then your visualizer
     just needs to keep the SelectionManager's content up to date)

  - when your visualizer's selection changes (i.e. by the user clicking
    or dragging on the visualizer's control, update the exposed
    selection (i.e. update the SelectionManager instance)

  - optionally, to enable toolbar/menu support:
    - implement createActions()/updateActions() to create and
        update the enabling of your actions
    - implement populateToolbar() to add actions to the visualizer toolbar
      (note: the toolbar is initially empty each time this is called)
    - implement populateMenu() to add actions to the toolbar's menu
    - implement populateContextMenu() to add actions to the
      VisualizerView's context menu
    - whenever the selection changes (workbench or visualizer),
      invoke updateActions() to keep your toolbar/menu actions
      enabled properly

- If you use the GraphicCanvasVisualizer, here's some additional hints:

  - create an internal "model" class for your canvas, if you don't
    already have such a model

  - when the workbench selection changes update this model
    with any needed changes; this allows you to decouple the
    canvas repaint step from workbench events,

  - have your GraphicCanvas implementation create and update instances
    of GraphicObject classes associated with your model objects;
    also cache GraphicObjects for model state that doesn't
    change on every repaint

  - don't repaint your visualizer canvas on every event;
    use a Timer instance and "batch up" requests that come in
    during the timer interval (for example, start the timer when
    the first update request comes in, and when the timer goes off,
    display the current state, effectively "rolling up" any update
    requests that came in during the timer interval)

  - add selection support to your canvas (i.e. let the user click-
    and drag-select items in the visualization), and use the
    selection-management interface of the IVisualizer class to
    expose this to the workbench

  - remember that the IVisualizerViewer/IVisualizer API provides
    support for a context menu on the visualizer, so you don't need
    to provide one for your canvas control

- Remember the goal of the visualizer: to provide a clear, high-level
  view of the selected object -- for example, the hierarchy of processes
  and threads in a running program. You can provide options or overlays
  for additional detail, but keep the basic picture simple.


Current State, Future Plans
---------------------------

- In the initial implementation, the IVisualizer implementation 
  is required to use the selection to locate the object (i.e. the current launch)
  that it is to represent visually, and to construct and maintain
  a graphic representation of it.

- In future, the Visualizer framework will want to provide APIs
  that factor out and simplify common aspects of interaction with
  launches and launch targets. For example:

  - a service-based target introspection layer, which can be used by
      IPresentation implementations to discover details of the current
      launch target in a platform-neutral way