public interface Renderer
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:
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.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.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);
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.
Modifier and Type | Method and 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 |
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. |
String getDisplayName()
void preProcess(PreviewModel previewModel)
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)
.
previewModel
- the model to get items fromvoid render(Item item, RenderTarget target, PreviewProperties properties)
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.
item
- the item to be renderedtarget
- the target to render the item onproperties
- the central propertiesPreviewProperty[] getProperties()
PreviewProperty.createProperty()
methods.boolean isRendererForitem(Item item, PreviewProperties properties)
properties
, determine whether this renderer is
valid to render Item
.
Additional states in properties
helps to make a decision,
including:
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.item
- the item to be testedproperties
- the current propertiestrue
if item
can be rendered by this
renderer, false
otherwiseboolean needsItemBuilder(ItemBuilder itemBuilder, PreviewProperties properties)
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:
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.itemBuilder
- builder that your renderer may needproperties
- the current propertiestrue
if you are going to use built items for rendering, false
otherwiseCanvasSize getCanvasSize(Item item, PreviewProperties properties)
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.item
- the item to get the canvas sizeproperties
- the current propertiesCopyright © 2007–2017 Gephi Consortium. All rights reserved.