sk.uniba.euromath.editor
Interface IRenderer

All Known Implementing Classes:

ImageRenderer

public interface IRenderer

Renderer produces graphical representation of given data. Displays nodes from one namespace only. For each nametree present in transformed document a separate instance of renderer is constructed.

First the init(Source, RendererContext) method is called to initialize the renderer. After the initialization the renderer must be able to provide drawing size, figures, and must be able to paint itself on a Graphics instance. reinit(IChangeCollector) may be called at any time to inform renderer of partial data change.

Renderer can support only two kinds of sources: the DOMSource and ObjectSource:

• They can be easily accessed multiple times without modification
• Changes can be managed easily

Instance of renderer is always used by a single thread - it should not be synchronized, resulting in faster execution.

Author:

Tomáš Studva, Martin Vysny

Method Summary

IInputPreprocessor	createPreprocessor() Constructs new instance of preprocessor.
org.eclipse.draw2d.geometry.Dimension	getCanvasSize() Retrieves size of area where the rendering occurs.
IEMFigure	getFigure(Object o) Retrieves figure that displays given data object.
RendererInfo	getInfo() Returns instance of RendererInfo able to create this renderer.
org.eclipse.draw2d.geometry.Point	getPlacement(String id) Returns point, relative to renderer's canvas, where canvas of child renderer will be positioned.
IEMFigure	getRootFigure() Retrieves the root figure, where all figures will be placed.
void	init(Source transformedDoc, RendererContext context) Initializes the renderer.
Object	offerObject() When the renderer accepts the ObjectSource but wants to provide an object as a result (for example it wants the document producer to draw something in a certain instance of Graphics), then return non-null value.
void	reinit(IChangeCollector changes) Reinitialize the renderer when a partial change of the rendered document occurs.
void	render(org.eclipse.draw2d.Graphics g) Paint rendered view to Graphics.

Method Detail

init

void init(Source transformedDoc,
          RendererContext context)
          throws EditorException

Initializes the renderer. Called as the first method (only the offerObject() and getInfo() methods may be called before this method). Renderer should prepare IFigure instances for future rendering.

If an element from another namespace occurs (generef processing instruction in case of DOMSource - you can retrieve id using SplittedDocHolder.getRef(org.w3c.dom.Node) function, or a custom object type in case of ObjectSource), the following steps are to be taken:

1. Renderer must query the context instance using this ID. It then receives the child renderer's canvas size.
2. Renderer must leave place for each child renderer canvas somewhere on its canvas, during the rendering process. It is not recommended to paint anything into that area - it gets covered by a Composite widget.
3. After the init ends, the renderer can be queried at any time for the child renderer placement using the getPlacement(String) method.

Parameters:

transformedDoc - fragment of document, DOMSource or ObjectSource instance. This nametree is to be rendered by the renderer. Renderer is encouraged to throw any exception including ClassCastException if it encounters illegal objects, to detect invalid objects quickly and cleanly.

context - the context instance, allows you to ask for child renderers output, etc.

Throws:

EditorException - if initialization fails.

getPlacement

org.eclipse.draw2d.geometry.Point getPlacement(String id)

Returns point, relative to renderer's canvas, where canvas of child renderer will be positioned.

Parameters:

id - the child nametree's ID.

Returns:

point, may be null if the child renderer's canvas is not visible (not placed anywhere).

reinit

void reinit(IChangeCollector changes)
            throws EditorException

Reinitialize the renderer when a partial change of the rendered document occurs. Renderer should discard IFigures no longer needed, and prepare new IFigures. This changed object is given to an editor when this method finishes, to allow the editor to query for new figures.

Parameters:

changes - defines changed elements. Has appropriate type for transformedDoc parameter, i.e. DOMChangeCollector for DOMSource etc. Contains source with all changes already applied.

Throws:

EditorException - if error occurs.

getCanvasSize

org.eclipse.draw2d.geometry.Dimension getCanvasSize()
                                                    throws EditorException

Retrieves size of area where the rendering occurs.

Returns:

dimension in pixels, never null.

Throws:

EditorException - if error occurs.

getFigure

IEMFigure getFigure(Object o)

Retrieves figure that displays given data object. The figure may contain child figures when required.

Parameters:

o - the data object, may be any object instance when transformed document is in form of ObjectSource, or a Node instance otherwise.

Returns:

root of view

getRootFigure

IEMFigure getRootFigure()

Retrieves the root figure, where all figures will be placed.

Returns:

root of rendered view.

render

void render(org.eclipse.draw2d.Graphics g)
            throws EditorException

Paint rendered view to Graphics. Use the context object to let the children renderers to paint.

Parameters:

g - paint onto this graphics instance.

Throws:

EditorException - if error occurs.

offerObject

Object offerObject()

When the renderer accepts the ObjectSource but wants to provide an object as a result (for example it wants the document producer to draw something in a certain instance of Graphics), then return non-null value. If this functionality is not needed then just return null - if the document producer requires some object then it can create any object as long as it is instance of class that this exporter expects.

The consumer (the one that receives the object, i.e. this) is responsible for freeing the object if necessary (at the end of the export method), even if this function returned null.

If you want producer (the one that creates the object) to create custom instances then provide a factory object. This trick is used with http://www.uniba.sk/euromath/holder/java.awt.Graphics holder - a factory is returned that is able to produce java.awt.Graphics instances.

This method can be called anytime, and is usually called before init(Source, RendererContext).

Returns:

the object instance, or null.

getInfo

RendererInfo getInfo()

Returns instance of RendererInfo able to create this renderer.

Returns:

the info object for this renderer.

createPreprocessor

IInputPreprocessor createPreprocessor()

Constructs new instance of preprocessor.

Returns:

new instance of preprocessor. If null then no preprocessor is needed and will be ignored.