## page was renamed from Cytoscape_3.0/PresentationDiscussions
= Presentation Layer =

'''Updated on July 15, 2009 by KeiOno'''

'''Still under construction!'''

== Introduction ==
Presentation layer is the set of actual classes which draws network graphics.  From 3.0, Cytoscpae can have multiple presentation per view.  This means multiple rendering engines can co-exist in an instance of Cytoscape.

== Design ==

=== Definitions ===
===== Data Model =====
 * All kinds of data objects, including CyNetwork, CyDataTables, VisualStyles, etc.

===== View Model =====
 * A map from Visual Property type to a value (color, size, ...)
 * One View Model is always associated with a data model.
 * A data model can have multiple View Models.

===== Presentation =====
 * '''''Presentation''''' is a visualization of '''''View Model'''''.  A View Model can have multiple presentations.  In reality, presentation represents a drawing on AWT Canvas or other Swing Components.

 
=== API ===
There are 3 interfaces in Presentation API bundle:

 * PresentationFactory - Provide a function to add Presentation as Swing Component to a given object.  '''''This factory accepts one or more views.'''''
 * VisualItemRenderer - Provide a VisualLexicon for a specific type of view object.
 * RenderingEngine - Render the entire scene.  Multiple View Models can be rendered in one canvas.

{{{#!java
public interface PresentationFactory {
	/*
	 * A presentation can contain multiple view models.
	 * This enable developers to render multiple View Models in the same display.
	 * For example, if View<CyNetwork> with View<Decoration> as child is passed to this, 
	 * both of them will be rendered in a window, using same rendering engine.
	 */
	public RenderingEngine addPresentation(Container container, View<?> viewModel);
}
}}}

{{{#!java
public interface VisualItemRenderer<T extends View<?>> {
	/**
	 * Provide a set of Visual Properties this renderer can visualize.
	 *
	 * @return Set of VP as a VisualLexicon
	 */
	public VisualLexicon getVisualLexicon();
}
}}}

{{{#!java
public interface RenderingEngine {
	
	/**
	 * Returns backend View Models for this presentation.
	 * 
	 * @return view models.
	 */
	public List<View<?>> getRootViewModel();
	

	/**
	 * Rendering engine dependent properties, like LOD
	 */
	public void setProperties(Properties props);
	public Properties getProperties();

	/**
	 * For export image function.
	 * 
	 * @return DOCUMENT ME!
	 */
	public Printable getPrintable();

	/**
	 * Render image from the current view model state.
	 * 
	 * @return Image object created from current window.
	 */
	public Image getImage(int width, int height);

	/**
	 * For a given Visual Property, render an Icon based on the default value of
	 * the Visual Property.
	 * 
	 * @param vp
	 *            Visual Property.
	 * 
	 * @return DOCUMENT ME!
	 * 
	 * @exception IllegalArgumentException
	 *                if vp is not in the lexicon.
	 */
	public Icon getDefaultIcon(VisualProperty<?> vp);
}
}}}


==== Discussion ====
Our overall design (model-view-presentation) does not completely equivalent to typical scene graph used in many 3D visualizers.  This design is inspired by Prefuse Visualization Toolkit.  The rendering engine object can take any type of Views, but usually it takes Networks or data tables.  For each View, render the object using proper VisualItemRenderer.  VisualItemRenderer provides a Visual Lexicon, which is a set of Visual Properties that can be recognized by this rendering engine's drawing classes.

A presentation can be created from multiple view models.  This makes renderer more flexible because the engine can render network(s) and other data objects (like decoration network) in the same canvas.


We need to add hierarchy to View Model to support views on a canvas:

{{{#!java
public class View<T> {
  public Collection<View<?>> getChildren();
  public boolean isLeaf();
}
}}}

Then, rendering engine can traverse this View Model Tree to draw all underlaying Views.

=== Relationship between Presentation Layer and Other Modules ===


== VizMap ==