Package org.gephi.preview.spi

Interface Renderer

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

Modifier and Type	Method	Description
CanvasSize	getCanvasSize(Item item, PreviewProperties properties)	Compute the canvas size of the item to render.
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	postProcess(PreviewModel previewModel, RenderTarget target, PreviewProperties properties)	This method is called after rendering all items to perform post-processing.
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

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 G2DTarget, 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

postProcess

void postProcess(PreviewModel previewModel,
                 RenderTarget target,
                 PreviewProperties properties)

This method is called after rendering all items to perform post-processing.

This method has access to the model but also to the target and properties.

Parameters:

previewModel - the model to get items from

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:

• PreviewProperty.DIRECTED: If the graph is directed
• PreviewProperty.MOVING: Specific to the Processing target, this is true if the user is currently moving the canvas. Renderers other than the node renderer usually render nothing while the user is moving to speeds things up.

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:

• PreviewProperty.DIRECTED: If the graph is directed
• PreviewProperty.MOVING: Specific to the Processing target, this is true if the user is currently moving the canvas. Renderers other than the node renderer usually render nothing while the user is moving to speeds things up.

Parameters:

itemBuilder - builder that your renderer may need

properties - the current properties

Returns:

true if you are going to use built items for rendering, false otherwise

getCanvasSize

CanvasSize getCanvasSize(Item item,
                         PreviewProperties properties)

Compute the canvas size of the item to render.

The returned CanvasSize has to embed the whole item to render. If the canvas size cannot be computed, a CanvasSize with both width and height equlal to zero is returned.

Parameters:

item - the item to get the canvas size

properties - the current properties

Returns:

the item canvas size