Gephi Toolkit Javadoc

org.gephi.preview.spi
Interface Renderer

All Known Implementing Classes:
ArrowRenderer, EdgeLabelRenderer, EdgeRenderer, NodeLabelRenderer, NodeRenderer

public interface Renderer

Renderer describes how a particular Item object is rendered on a particular RenderTarget instance.

Renderers are the most essential parts of the Preview as they contain the code that actually draws the item on the canvas. Each item (e.g. node, edge) should have its renderer.

Rendering is a three-steps process:

  1. First the preProcess() method is called on all renderers to let them initialize additional attributes for their items. The best example is the edge renderer which will initialize the source and target position in the EdgeItem object during this phase. In general the preProcess() method is the best for complex algorithms or gathering data from other items. Note that the preProcess() method is called only once per refresh, unlike render() which is called many times.
  2. The isRendererForitem() is then used to determine which renderer should be used to render an item. The method provides an access to the preview properties. For instance, if the properties says the edge display is disabled, the edge renderer should return false for every item. Note that nothing avoids several renderer to returns true for the same item.
  3. The render() method is finally called for every item which the renderer returned true at isRendererForitem(). It receives the properties and the render target. It uses the item attributes and properties to determine item aspects and the render target to obtain the canvas.

Renderers also provide a list of PreviewProperty which the user can edit. All properties are put in the central PreviewProperties so though each renderer defines it's properties it can read/write any property through PreviewProperties.

If your plugin renderer extends one of the default renderers, your plugin renderer will automatically replace the extended renderer. This means the default renderer will not even be available in the renderers manager.

Also, if more than one plugin extends the same default renderer, the one with lowest position will be enabled by the default, but others will still be available for activation in the renderers manager.

The list of default renderers is the following (contained in Preview Plugin module);

  1. org.gephi.preview.plugin.renderers.ArrowRenderer
  2. org.gephi.preview.plugin.renderers.EdgeLabelRenderer
  3. org.gephi.preview.plugin.renderers.EdgeRenderer
  4. org.gephi.preview.plugin.renderers.NodeLabelRenderer
  5. org.gephi.preview.plugin.renderers.NodeRenderer

Renderers are singleton services and implementations need to add the following annotation to be recognized by the system:

@ServiceProvider(service=Renderer.class, position=XXX) Position parameter optional but recommended in order to control the default order in which the available renderers are executed.

Author:
Yudi Xue, Mathieu Bastian

Method Summary
 java.lang.String getDisplayName()
          Provides an user friendly name for the renderer.
 PreviewProperty[] getProperties()
          Returns all associated properties for this renderer.
 boolean isRendererForitem(Item item, PreviewProperties properties)
          Based on properties, determine whether this renderer is valid to render Item.
 boolean needsItemBuilder(ItemBuilder itemBuilder, PreviewProperties properties)
          Based on the itemBuilder class and the properties, determine whether this renderer needs the given itemBuilder to be executed before rendering.
 void preProcess(PreviewModel previewModel)
          This method is called before rendering for all renderers and initializes items' additional attributes or run complex algorithms.
 void render(Item item, RenderTarget target, PreviewProperties properties)
          Render item to target using the global properties and item data.
 

Method Detail

getDisplayName

java.lang.String getDisplayName()
Provides an user friendly name for the renderer. This name will appear in the renderers manager UI.

Returns:
User friendly renderer name, not null

preProcess

void preProcess(PreviewModel previewModel)
This method is called before rendering for all renderers and initializes items' additional attributes or run complex algorithms.

This method has access to any item using the getItems() methods of the preview model.

No data should be stored in the renderer itself but put in items using Item.setData(java.lang.String, java.lang.Object). Global states can be stored in properties using PreviewProperties.putValue(java.lang.String, java.lang.Object).

Parameters:
previewModel - the model to get items from

render

void render(Item item,
            RenderTarget target,
            PreviewProperties properties)
Render item to target using the global properties and item data.

The target can be one of the default target ProcessingTarget, SVGTarget or PDFTarget. Each target contains an access to it's drawing canvas so the renderer can draw visual items.

Parameters:
item - the item to be rendered
target - the target to render the item on
properties - the central properties

getProperties

PreviewProperty[] getProperties()
Returns all associated properties for this renderer. Properties can be built using static PreviewProperty.createProperty() methods.

Returns:
a properties array

isRendererForitem

boolean isRendererForitem(Item item,
                          PreviewProperties properties)
Based on properties, determine whether this renderer is valid to render Item.

Additional states in properties helps to make a decision, including:

Parameters:
item - the item to be tested
properties - the current properties
Returns:
true if item can be rendered by this renderer, false otherwise

needsItemBuilder

boolean needsItemBuilder(ItemBuilder itemBuilder,
                         PreviewProperties properties)
Based on the itemBuilder class and the properties, determine whether this renderer needs the given itemBuilder to be executed before rendering.

This is used for avoiding building unnecessary items while refreshing preview.

You can simply return true if the builder builds items that this renderer renders, but you can also check the current properties to see if your renderer is going to produce any graphic.

Additional states in properties helps to make a decision, including:

Parameters:
itemBuilder - builder that your renderer may need
properties - Current properties
Returns:
true if you are going to use built items for rendering, false otherwise

Gephi Toolkit Javadoc