ilog.views.sdm.renderer

Class IlvSDMRenderer

java.lang.Object

ilog.views.sdm.renderer.IlvSDMRenderer

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

IlvFilterSDMRenderer, IlvStyleSheetRenderer

public abstract class IlvSDMRenderer
extends Object
implements Serializable

The class IlvSDMRenderer is the base class for the renderers used in an SDM engine.

The purpose of a renderer is to implement a particular policy for rendering the objects of an SDM data model as Rogue Wave JViews graphic objects in a Rogue Wave JViews grapher.

The renderers attached to an SDM engine form a chained list. The first element of this list is set using the method setRenderer. All but the last element of the list are instances of IlvFilterSDMRenderer. The next element in the list is defined by the method setFilteredRenderer. The last element of the list is usually an instance of IlvStyleSheetRenderer.

Style Sheet Renderer

The main renderer is the IlvStyleSheetRenderer. The style sheet renderer reads a file in the CSS syntax, and creates and customizes JViews graphic objects according to the CSS rules. For example, the following rule states that all nodes of the SDM data model shall be represented by JViews IlvRectangle objects, and the rectangles shall be green.

   node {
     class : "ilog.views.graphic.IlvRectangle";
     foreground : "green";
   }
 

Filtering Renderers

Other renderers can be combined with the style sheet renderer to modify the look or the behavior of the graphic objects. This combination of renderers is implemented by way of "filtering" renderers (see IlvFilterSDMRenderer). Several filtering renderers can be added in front of the style sheet renderer to add different aspects to the rendering process. For example, the IlvHalfZoomingRenderer prevents nodes from zooming or unzooming too much. Another example is the IlvExpandCollapseRenderer that shows sub-graphs of the data model as special expandable and collapsible nodes.

Rendering Properties

Renderers usually require information to know how to create and customize graphic objects. This information can be specified in the style sheet file, just like the plain properties of graphic objects. For example, if a half-zooming renderer is used, you could add the following declaration to say that the nodes must not zoom beyond a zoom level of 4:

   node {
     class : "ilog.views.graphic.IlvRectangle";
     foreground : "green";
     MaxZoomLevel : "4.0";
   }
 

These special rendering properties are fetched through the method IlvRendererUtil.getGraphicProperty(ilog.views.sdm.IlvSDMEngine, java.lang.Object, java.lang.String, java.lang.String[], java.lang.Class<?>), or one of its variants that convert the property value to an appropriate type.

Note that, by convention, the rendering properties are capitalized to distinguish them from plain properties of IlvGraphic objects.

Pseudo classes

Pseudo classes are strings that can be used to mark data objects. The purpose of pseudo classes is to allow renderers to give feedback to the user on the state of an object by displaying it in a different way.

The style sheet can contain rules that apply only when the object has a particular pseudo class.

For example, the SDM engine adds the pseudo class "selected" to selected objects. The following style sheet rule says that selected objects are red:

   node:selected {
     foreground : "red";
   }
 

The pseudo classes of a data object are passed along to several methods of IlvSDMRenderer to let any renderer decide what it should do depending on the object pseudo classes.

The class IlvSDMRenderer is abstract: subclasses need to define at least the methods createNodeGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object) and createLinkGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, ilog.views.IlvGraphic).

Since:

JViews 4.0

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static String	PSEUDOCLASS_PREFIX This prefix gets added to a pseudo-class name, when treating a pseudoclass change like a property change.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	IlvSDMRenderer() Creates a new SDM renderer.

Method Summary

Modifier and Type	Method and Description
void	addLinkGraphic(IlvSDMEngine engine, Object link, IlvGraphic graphic, boolean redraw) Adds the graphic object, which has previously been returned by createLinkGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, ilog.views.IlvGraphic) to represent the specified data object link, to the grapher associated with the SDM engine.
void	addNodeGraphic(IlvSDMEngine engine, Object node, IlvGraphic graphic, boolean redraw) Adds the graphic object, which has previously been returned by createNodeGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object) to represent the specified data object node, to the grapher associated with the SDM engine.
protected void	addViewListeners(IlvManagerView view) This method can be overridden to add view listeners on any view attached to an SDM engine.
void	callMoveResizeNodeGraphic(IlvSDMEngine engine, Object node, IlvGraphic graphic, IlvRect newBBox, int anchor) Move the graphic to its final position Note: If the graphic object is contained inside an IlvManager, users must use the method IlvManager.applyToObject(ilog.views.IlvGraphic, ilog.views.IlvApplyObject, java.lang.Object, boolean) to call this method.
IlvRect	computeBBox(IlvSDMEngine engine, IlvManagerView view, IlvTransformer t) Computes the rectangle that contains all the graphic objects of the manager for a given view.
protected Object	convert(Object source, Class<?> target, String property) Converts a value to the type expected for a given property of a given class.
protected Object	convert(Object source, PropertyDescriptor pd, Class<?> targetClass) Converts a value to the type defined by a given PropertyDescriptor.
abstract IlvGraphic	createLinkGraphic(IlvSDMEngine engine, Object link, IlvGraphic from, IlvGraphic to) Creates a Rogue Wave JViews graphic object that will represent the specified link of the data model.
abstract IlvGraphic	createNodeGraphic(IlvSDMEngine engine, Object node) Creates a Rogue Wave JViews graphic object that will represent the specified node of the data model.
void	customize(IlvSDMEngine engine, Object object, IlvGraphic g, String[] pseudoClasses) Sets the properties of a graphic object that represents a data object.
String	getAlias() Returns the alias of this renderer.
Object	getAuxiliaryBean() Deprecated. Beginning with JViews 6.0, you should override getAuxiliaryBeans() instead.
Object[]	getAuxiliaryBeans() Returns auxiliary objects used by the renderer, so that these auxiliary objects can be customized in the style sheet.
IlvGraphic	getEncapsulatedGraphic(IlvGraphic graphic) If the renderer decides to encapsulate a graphic object created by another renderer, this method must return the encapsulated graphic.
IlvSDMEngine	getEngine() Returns the IlvSDMEngine instance that has created this renderer.
Object	getGraphicProperty(IlvSDMEngine engine, Object object, String property, String[] pseudoClasses, Class<?> targetClass) Gets the value of a property used to render an object graphically.
IlvRect	getLinkConnectionRectangle(IlvSDMEngine engine, IlvGraphic graphic, IlvTransformer t) Returns a rectangle on which the connection points of the links to/from a node should be located.
IlvRect	getLinkConnectionRectangle(IlvSDMEngine engine, IlvGraphic graphic, IlvTransformer t, IlvLinkConnector lc) Returns a rectangle on which the connection points of the links to/from a node should be located.
protected boolean	getLocation(IlvSDMEngine engine, Object node, IlvPoint point) This method retrieves the "x" and "y" graphic properties and places the result in the point parameter.
String	getParameter() This method gives access to the main parameter of the renderer.
void	linkGraphicAdded(IlvSDMEngine engine, Object link, IlvGraphic graphic, boolean redraw) Called immediately after addLinkGraphic by the SDM engine.
protected void	moveResizeNodeGraphic(IlvSDMEngine engine, Object node, IlvGraphic graphic, IlvRect newBBox, int anchor) Move the graphic to its final position
protected boolean	needsViewListeners() This method can be overridden to specify that this renderer needs to add listeners on all the views attached to the grapher of the SDM engine.
void	nodeGraphicAdded(IlvSDMEngine engine, Object node, IlvGraphic graphic, boolean redraw) Called immediately after addNodeGraphic by the SDM engine.
void	nodeGraphicBBoxChanged(IlvSDMEngine engine, Object node, IlvGraphic graphic, IlvRect oldBBox, IlvRect newBBox, String[] pseudoClasses) This method is called when the graphic object representing a node of the data model has been moved and/or resized, either by a user interaction or by a direct call to the Rogue Wave JViews API.
void	prepareRendering(IlvSDMEngine engine) Prepares the renderer for rendering objects in the specified SDM engine.
boolean	processServerAction(int x, int y, IlvManagerView view) This method is called when the SDM is used on the server-side of a web application, to process an action sent by the client-side.
void	propertiesChanged(IlvSDMEngine engine, Object object, Collection<String> propertyNames, IlvGraphic graphic) Updates the graphic representation of a data object.
void	propertyChanged(IlvSDMEngine engine, Object object, String propertyName, Object oldValue, Object newValue, IlvGraphic graphic) Deprecated. Since JViews 8.5, property changes do not notify this method any more. Instead of overriding this method, better override the propertiesChanged(ilog.views.sdm.IlvSDMEngine, java.lang.Object, java.util.Collection<java.lang.String>, ilog.views.IlvGraphic) method.
void	removeAll(IlvSDMEngine engine) Cleans up the internal state of the renderer.
void	removeLinkGraphic(IlvSDMEngine engine, Object link, IlvGraphic graphic, boolean redraw) Removes a graphic object representing a link of the SDM data model from the grapher.
void	removeNodeGraphic(IlvSDMEngine engine, Object node, IlvGraphic graphic, boolean redraw) Removes a graphic object representing a node of the SDM data model from the grapher.
protected void	removeViewListeners(IlvManagerView view) This method can be overridden to remove view listeners from any view attached to an SDM engine.
void	renderingDone(IlvSDMEngine engine) This method is called when the SDM engine has finished rendering the data model, and every time an object is dynamically added to the data.
void	setAlias(String alias) Sets the alias of this renderer.
void	setEngine(IlvSDMEngine engine) Sets the IlvSDMEngine instance that has created this renderer.
protected void	setLayerName(IlvGrapher grapher, int layer, String name) Sets the name of the specified layer.
void	setParameter(String parameter) This method gives access to a privileged parameter of the renderer, and allows this parameter to be specified quickly in the main option rule of the style sheet.
void	updateObjectProperties(IlvSDMEngine engine, Object object, String property, Object value, String[] pseudoClasses) Updates a data object when a property of the graphic object that represents it changes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PSEUDOCLASS_PREFIX

public static final String PSEUDOCLASS_PREFIX

This prefix gets added to a pseudo-class name, when treating a pseudoclass change like a property change.

Since:

JViews 8.5

See Also:

Constant Field Values

Constructor Detail

IlvSDMRenderer

protected IlvSDMRenderer()

Creates a new SDM renderer.

Method Detail

setAlias

public void setAlias(String alias)

Sets the alias of this renderer. The alias is the symbolic name used to designate the renderer in the SDM style sheet, for example SubGraph or GraphLayout.

Parameters:

alias - The new alias.

Since:

JViews 5.5

getAlias

public String getAlias()

Returns the alias of this renderer. If no alias was set explicitly using setAlias(java.lang.String), the alias associated with this renderer's class is returned.

Since:

JViews 5.5

See Also:

IlvRendererUtil.addRendererAlias(java.lang.String, java.lang.String), IlvRendererUtil.getRendererAlias(java.lang.String)

setEngine

public void setEngine(IlvSDMEngine engine)

Sets the IlvSDMEngine instance that has created this renderer. This method is called by the SDM engine, you should not call it directly.

Since:

JViews 6.0

getEngine

public IlvSDMEngine getEngine()

Returns the IlvSDMEngine instance that has created this renderer.

Since:

JViews 6.0

createNodeGraphic

public abstract IlvGraphic createNodeGraphic(IlvSDMEngine engine,
                                             Object node)

Creates a Rogue Wave JViews graphic object that will represent the specified node of the data model.

This method is called by the SDM engine every time a node of the SDM data model must be rendered, that is:

• When the data model is loaded or re-loaded.
• When a new node is added dynamically to the data model.

This method must return a new IlvGraphic whose properties are set according to the type and properties of the corresponding data object. The graphic object must not be added to the grapher yet: this will be done by the method addNodeGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, boolean).

The renderer can decide to return null from this method: in that case, the object will not be rendered at all.

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object will be added.

node - The data node to translate into an IlvGraphic.

createLinkGraphic

public abstract IlvGraphic createLinkGraphic(IlvSDMEngine engine,
                                             Object link,
                                             IlvGraphic from,
                                             IlvGraphic to)

Creates a Rogue Wave JViews graphic object that will represent the specified link of the data model.

This method is called by the SDM engine every time a link of the SDM data model must be rendered, that is:

• When the data model is loaded or re-loaded.
• When a new link is added to the data model.

This method must return a new IlvGraphic (usually an IlvLinkImage) whose properties are set according to the type and properties of the corresponding data object. The graphic object must not be added to the grapher yet: this will be done by the method addLinkGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, boolean).

The renderer can decide to return null from this method: in that case, the object will not be rendered at all.

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object will be added.

link - The data link to translate into an IlvGraphic.

from - The graphic object associated with the source node of the link.

to - The graphic object associated with the destination node of the link.

addNodeGraphic

public void addNodeGraphic(IlvSDMEngine engine,
                           Object node,
                           IlvGraphic graphic,
                           boolean redraw)

Adds the graphic object, which has previously been returned by createNodeGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object) to represent the specified data object node, to the grapher associated with the SDM engine.

This method is called by the SDM engine every time a node of the SDM data model is rendered, just after createNodeGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object).

This method is mainly responsible for choosing the layer in which the graphic object will be added.

The default implementation adds the node in the default insertion layer of the grapher.

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object will be added.

node - The node that is being translated into an IlvGraphic.

graphic - The graphic object returned by createNodeGraphic.

redraw - If true, the region covered by the new graphic object must be redrawn.

addLinkGraphic

public void addLinkGraphic(IlvSDMEngine engine,
                           Object link,
                           IlvGraphic graphic,
                           boolean redraw)

Adds the graphic object, which has previously been returned by createLinkGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, ilog.views.IlvGraphic) to represent the specified data object link, to the grapher associated with the SDM engine.

This method is called by the SDM engine every time a link of the SDM data model is rendered, just after createLinkGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, ilog.views.IlvGraphic).

This method is mainly responsible for choosing the layer in which the graphic object will be added.

The default implementation adds the link in the default insertion layer of the grapher.

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object will be added.

link - The link that is being translated into an IlvGraphic.

graphic - The graphic object returned by createLinkGraphic.

redraw - If true, the region covered by the new graphic object must be redrawn.

nodeGraphicAdded

public void nodeGraphicAdded(IlvSDMEngine engine,
                             Object node,
                             IlvGraphic graphic,
                             boolean redraw)

Called immediately after addNodeGraphic by the SDM engine.

The purpose of this method is to allow filtering renderers to redefine the addNodeGraphic method without calling their superclass.

The addNodeGraphic method actually adds the object in the grapher. For this reason, if it is overridden, it does not need to call the superclass (because the object would be added twice). This method, on the other hand, is called after the object is added to allow any additional processing to be performed. For this reason, if this method is overridden, it must call the superclass to ensure that all other renderers are called.

So, if a renderer needs to modify the graphic object once it has been added in the grapher (for example, to add an object interactor), it should do it in this method, instead of doing it in addNodeGraphic.

The default implementation of this method does nothing.

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object has been added.

node - The object that is being translated into an IlvGraphic.

graphic - The graphic object that has just been added to the grapher.

redraw - If true, the region covered by the new graphic object must be redrawn.

Since:

JViews 5.0

See Also:

addNodeGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, boolean)

linkGraphicAdded

public void linkGraphicAdded(IlvSDMEngine engine,
                             Object link,
                             IlvGraphic graphic,
                             boolean redraw)

Called immediately after addLinkGraphic by the SDM engine.

It is the equivalent of nodeGraphicAdded for links. See nodeGraphicAdded for a detailed explanation.

The default implementation of this method does nothing.

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object has been added.

link - The object that is being translated into an IlvGraphic.

graphic - The graphic object that has just been added to the grapher.

redraw - If true, the region covered by the new graphic object must be redrawn.

Since:

JViews 5.0

See Also:

addLinkGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, boolean)

setLayerName

protected final void setLayerName(IlvGrapher grapher,
                                  int layer,
                                  String name)

Sets the name of the specified layer. This method can be called by subclasses to give meaningful names to the layers in which the graphic objects are placed.

The layer name will possibly be suffixed with an index if it is already used.

Parameters:

grapher - The grapher to which the layer belongs.

layer - The layer index.

name - The new name of the layer.

removeNodeGraphic

public void removeNodeGraphic(IlvSDMEngine engine,
                              Object node,
                              IlvGraphic graphic,
                              boolean redraw)

Removes a graphic object representing a node of the SDM data model from the grapher.

This method is called when a node is removed from the data model, or when a new graphic object must be created because of a state change, but not when the grapher is cleaned up before loading a new data model or a new style sheet. In such a case, the removeAll(ilog.views.sdm.IlvSDMEngine) method is called to cleanup the renderer's internal state if needed, and all the graphic objects are removed from the grapher all at once by the SDM engine.

The default implementation simply calls IlvGrapher.removeNode(ilog.views.IlvGraphic, boolean).

Parameters:

engine - The SDM engine associated with the grapher from which the graphic object will be removed.

node - The node that has been removed or modified in the data model.

graphic - The graphic object that must be removed from the grapher.

redraw - If true, the region covered by the graphic object must be redrawn.

removeLinkGraphic

public void removeLinkGraphic(IlvSDMEngine engine,
                              Object link,
                              IlvGraphic graphic,
                              boolean redraw)

Removes a graphic object representing a link of the SDM data model from the grapher.

This method is called when a link is removed from the data model, or when a new graphic object must be created because of a state change, but not when the grapher is cleaned up before loading a new data model or a new style sheet. In such a case, the removeAll(ilog.views.sdm.IlvSDMEngine) method is called to cleanup the renderer's internal state if needed, and all the graphic objects are removed from the grapher all at once by the SDM engine.

The default implementation simply calls IlvGrapher.removeLink(ilog.views.IlvLinkImage, boolean).

Parameters:

engine - The SDM engine associated with the grapher from which the graphic object will be removed.

link - The link that has been removed or modified in the data model.

graphic - The graphic object that must be removed from the grapher.

redraw - If true, the region covered by the graphic object must be redrawn.

removeAll

public void removeAll(IlvSDMEngine engine)

Cleans up the internal state of the renderer.

This method is called by the SDM engine before a data model is loaded (and before the SDM engine clears the grapher's contents). It is also called when the renderer is detached from the SDM engine.

Subclasses that override this method must always call their superclass.

Parameters:

engine - The SDM engine.

prepareRendering

public void prepareRendering(IlvSDMEngine engine)

Prepares the renderer for rendering objects in the specified SDM engine.

This method is called just before the SDM engine starts rendering a new data model, before any createNodeGraphics or createLinkGraphics are called.

Subclasses that override this method must always call their superclass.

Parameters:

engine - The SDM engine.

renderingDone

public void renderingDone(IlvSDMEngine engine)

This method is called when the SDM engine has finished rendering the data model, and every time an object is dynamically added to the data.

Subclasses that override this method must always call their superclass.

Parameters:

engine - The SDM engine.

propertyChanged

@Deprecated
public void propertyChanged(IlvSDMEngine engine,
                                        Object object,
                                        String propertyName,
                                        Object oldValue,
                                        Object newValue,
                                        IlvGraphic graphic)

Deprecated. Since JViews 8.5, property changes do not notify this method any more. Instead of overriding this method, better override the propertiesChanged(ilog.views.sdm.IlvSDMEngine, java.lang.Object, java.util.Collection<java.lang.String>, ilog.views.IlvGraphic) method.

Updates the graphic representation of a data object.

This method is called by the SDM engine when a property of a data object has changed. It is responsible for setting the properties of the corresponding graphic object to reflect the change. The new look of the graphic object should be the same as if the data object had just been created in its current state.

The default implementation simply calls the customize(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, java.lang.String[]) method, which re-computes all the properties of the graphic object regardless of the precise property that has changed in the data object.

Note that the SDM engine can group property change events that occur inside a setAdjusting(true)/setAdjusting(false) sequence, so it is not guaranteed that every property change in the model will result in a call to this method.

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object is displayed.

object - The data object whose property has changed.

propertyName - The name of the property that has been modified.

oldValue - The old value of the property.

newValue - The new value of the property.

graphic - The graphic object associated with object.

propertiesChanged

public void propertiesChanged(IlvSDMEngine engine,
                              Object object,
                              Collection<String> propertyNames,
                              IlvGraphic graphic)

Updates the graphic representation of a data object.

This method is called by the SDM engine when some properties of a data object has changed. It is responsible for setting the properties of the corresponding graphic object to reflect the change. The new look of the graphic object should be the same as if the data object had just been created in its current state.

Pseudoclass changes are treated like property changes; the "property name" is the pseudoclass name, prefixed with PSEUDOCLASS_PREFIX.

The default implementation simply calls the customize(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, java.lang.String[]) method, which re-computes all the properties of the graphic object regardless of the precise property that has changed in the data object.

Note that the SDM engine can group property change events that occur inside a setAdjusting(true)/setAdjusting(false) sequence, so it is not guaranteed that every property change in the model will result in a call to this method.

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object is displayed.

object - The data object whose property has changed.

propertyNames - The names of the properties that have been modified. propertyNames == null stands for an unspecified set of properties (possibly all properties).

graphic - The graphic object associated with object.

Since:

JViews 8.5

getGraphicProperty

public Object getGraphicProperty(IlvSDMEngine engine,
                                 Object object,
                                 String property,
                                 String[] pseudoClasses,
                                 Class<?> targetClass)

Gets the value of a property used to render an object graphically.

This method is called by IlvRendererUtil.getGraphicProperty(ilog.views.sdm.IlvSDMEngine, java.lang.Object, java.lang.String, java.lang.String[], java.lang.Class<?>) on the root renderer attached to the SDM engine. The call is propagated to all the filtering renderers, down to the style sheet renderer. The style sheet renderer returns the value of the property as defined in the sheet for the specified object. The filtering renderers may then modify or replace the value if appropriate.

For example, the style sheet renderer reads the rendering properties ("x" and "y") to know where a node should be placed. These properties can be defined in the style sheet as follows:

   node {
     class : "ilog.views.graphic.IlvRectangle";
     x : "@positionX";
     y : "@positionY";
   }
 

(the "@" notation means that the values are read from a property of the data object).

Now, if an IlvMapRenderer is used, it will try to place the node according to its latitude and longitude. To do this, it will see if the data object has latitude and longitude properties, apply a cartographic projection to compute new values for x and y, and return these projected coordinates instead.

This basic implementation is used as a default case used when the property has not been specified in the style sheet and no filtering renderer decided to define it. This implementation returns the object property as defined by the SDM model, that is, engine.getModel().getObjectProperty(obj, property). This means that rendering properties can be defined directly in the data model, although this is not generally recommended, except perhaps for the object positions ("x" and "y", or "longitude" and "latitude").

Parameters:

engine - The SDM engine.

object - The data object that is being rendered.

property - The name of the graphic property.

pseudoClasses - The pseudo classes of the object. This parameter can be null.

targetClass - The class of the object on which the property will be set. The method can introspect the class to determine the type of the property (without namespace), and convert the value if necessary. If this argument is null, the property should be returned without conversion.

updateObjectProperties

public void updateObjectProperties(IlvSDMEngine engine,
                                   Object object,
                                   String property,
                                   Object value,
                                   String[] pseudoClasses)

Updates a data object when a property of the graphic object that represents it changes.

This method is the inverse of getGraphicProperty(ilog.views.sdm.IlvSDMEngine, java.lang.Object, java.lang.String, java.lang.String[], java.lang.Class<?>). As getGraphicProperty is meant to translate the properties of a data object into the properties of its corresponding graphic object, updateObjectProperties translates the properties of a graphic object into properties of the data object that it represents.

In practice, this method is used primarily to update the position properties of an object in the data model when a graphic object is moved in the SDM view.

This implementation sets the specified property directly on the data object, using the IlvSDMModel.setObjectProperty(java.lang.Object, java.lang.String, java.lang.Object) method. If the model is not editable, the method does nothing.

Parameters:

engine - The SDM engine.

object - The data object.

property - The name of the graphic property.

value - The new value of the property.

pseudoClasses - The pseudo classes of the objects. This parameter can be null.

convert

protected final Object convert(Object source,
                               Class<?> target,
                               String property)

Converts a value to the type expected for a given property of a given class. The type of the property in the specified class is determined using Java beans introspection, and the value is converted to this type.

Parameters:

source - The value to convert.

target - The class used to determine the property type.

property - The name of the property whose type the value must be converted to.

convert

protected final Object convert(Object source,
                               PropertyDescriptor pd,
                               Class<?> targetClass)

Converts a value to the type defined by a given PropertyDescriptor.

Parameters:

source - The value to be converted.

pd - The property descriptor specifying the type to convert the value to.

targetClass - The class used to determine the property type.

Returns:

The converted value. Primitive types are wrapped in their corresponding Object reference (for example, if the target type is int, the method will return an Integer).

getLinkConnectionRectangle

public final IlvRect getLinkConnectionRectangle(IlvSDMEngine engine,
                                                IlvGraphic graphic,
                                                IlvTransformer t)

Returns a rectangle on which the connection points of the links to/from a node should be located.

Since JViews 8.7, do not override this method. It calls getLinkConnectionRectangle(IlvSDMEngine,IlvGraphic,IlvTransformer,IlvLinkConnector) passing null as link connector, and that can be overridden.

Parameters:

engine - The SDM engine.

graphic - The graphic object returned by createNodeGraphic.

t - The transformer of the view.

Returns:

A rectangle in view coordinates.

getLinkConnectionRectangle

public IlvRect getLinkConnectionRectangle(IlvSDMEngine engine,
                                          IlvGraphic graphic,
                                          IlvTransformer t,
                                          IlvLinkConnector lc)

Returns a rectangle on which the connection points of the links to/from a node should be located. This method is either called from the link connector, which is passed as argument, or from the renderers with null as link connector argument.

This basic implementation returns the bounding box of the node. It should be overridden by subclasses if the nodes contain text labels and/or decoration icons.

Parameters:

engine - The SDM engine.

graphic - The graphic object returned by createNodeGraphic.

t - The transformer of the view.

lc - The link connector from which this is called. This can be null.

Returns:

A rectangle in view coordinates.

Since:

JViews 8.7

getEncapsulatedGraphic

public IlvGraphic getEncapsulatedGraphic(IlvGraphic graphic)

If the renderer decides to encapsulate a graphic object created by another renderer, this method must return the encapsulated graphic.

This basic implementation simply returns the graphic parameter.

Parameters:

graphic - A graphic object returned by createNodeGraphic.

customize

public void customize(IlvSDMEngine engine,
                      Object object,
                      IlvGraphic g,
                      String[] pseudoClasses)

Sets the properties of a graphic object that represents a data object.

This method is called by the SDM engine whenever the graphic representation of a data object must be updated, for example when the pseudo classes of the object are modified.

This basic implementation uses introspection to get the names of all the public properties of the specified graphic object. For each property, the getGraphicProperty method of the engine is called to ask any interested renderer a value for the property. If a non-null value is returned, the graphic object's property is set to this value.

Parameters:

engine - The SDM engine.

object - The data object that the graphic object represents.

g - The graphic object to customize.

pseudoClasses - The pseudo classes of the object. This parameter can be null.

nodeGraphicBBoxChanged

public void nodeGraphicBBoxChanged(IlvSDMEngine engine,
                                   Object node,
                                   IlvGraphic graphic,
                                   IlvRect oldBBox,
                                   IlvRect newBBox,
                                   String[] pseudoClasses)

This method is called when the graphic object representing a node of the data model has been moved and/or resized, either by a user interaction or by a direct call to the Rogue Wave JViews API.

The method is meant to allow the renderer to update the geometry of the object in the data model according to the new position of the graphic object. For this, the renderer should call updateObjectProperties(ilog.views.sdm.IlvSDMEngine, java.lang.Object, java.lang.String, java.lang.Object, java.lang.String[]).

The default implementation does nothing.

Parameters:

engine - The SDM engine.

node - The data node that the graphic object represents.

graphic - The graphic object that has been moved and/or resized.

oldBBox - The bounding box of the graphic object before the change.

newBBox - The bounding box of the graphic object after the change.

pseudoClasses - The pseudo classes of the object. This parameter can be null.

getLocation

protected final boolean getLocation(IlvSDMEngine engine,
                                    Object node,
                                    IlvPoint point)

This method retrieves the "x" and "y" graphic properties and places the result in the point parameter.

Parameters:

engine - The SDM engine to which this renderer is attached.

node - The data object whose position is requested.

point - An IlvPoint into which the computed position must be stored.

Returns:

true if the method found x and y on the node, and false otherwise.

setParameter

public void setParameter(String parameter)

This method gives access to a privileged parameter of the renderer, and allows this parameter to be specified quickly in the main option rule of the style sheet.

For example, the main parameter of the IlvMapRenderer is the name of the map file. You can specify that you want to display a map of the USA by the single declaration:

   SDM {
     Map : "usa.ivl";
   }
 

The default implementation does nothing. Subclasses should override this method to give access to their main parameter.

Parameters:

parameter - The value of the parameter.

getParameter

public String getParameter()

This method gives access to the main parameter of the renderer.

The default implementation returns null.

See Also:

setParameter(java.lang.String)

getAuxiliaryBean

@Deprecated
public Object getAuxiliaryBean()

Deprecated. Beginning with JViews 6.0, you should override getAuxiliaryBeans() instead.

Returns an auxiliary object used by the renderer, so that this auxiliary object can be customized in the style sheet.

If this method returns a non-null object, the user will be able to customize the properties of this object directly from the style sheet, in the same rules as the renderer itself.

See IlvGraphLayoutRenderer for an example of the use of this method.

The default implementation returns null.

getAuxiliaryBeans

public Object[] getAuxiliaryBeans()

Returns auxiliary objects used by the renderer, so that these auxiliary objects can be customized in the style sheet.

If this method returns a non-null array of objects, the user will be able to customize the properties of the objects directly from the style sheet, in the same rules as the renderer itself.

See IlvGraphLayoutRenderer and IlvLinkLayoutRenderer for examples of the use of this method.

The default implementation calls getAuxiliaryBean() for compatibility. If getAuxiliaryBean() returns a non-null object, an array containing this object is returned.

Since:

JViews 5.5

computeBBox

public IlvRect computeBBox(IlvSDMEngine engine,
                           IlvManagerView view,
                           IlvTransformer t)

Computes the rectangle that contains all the graphic objects of the manager for a given view.

The default implementation calls IlvManagerView.computeBBox(). This method can be overridden by subclasses of IlvSDMRenderer, for example to ignore certain graphic objects in the computation of the view's bounds.

Parameters:

engine - The SDM engine.

view - The manager view for which the bounding rectangle is computed.

t - The transformer used to compute the bounding box. A null value is equivalent to an identity transformer.

Returns:

The resulting rectangle.

Since:

JViews 5.5

needsViewListeners

protected boolean needsViewListeners()

This method can be overridden to specify that this renderer needs to add listeners on all the views attached to the grapher of the SDM engine.

If this method returns true, then the SDM renderer will make sure that the methods addViewListeners(ilog.views.IlvManagerView) and removeViewListeners(ilog.views.IlvManagerView) are called as appropriate for each view attached to the SDM engine.

For example, if your renderer needs to install a transformer listener on all views (for example to adjust the graphic objects when the view is zoomed or unzoomed), you would override the needsViewListeners method to return true and the add/removeViewListener methods to add/remove your transformer listener.

If this method returns false, then the methods addViewListeners(ilog.views.IlvManagerView) and removeViewListeners(ilog.views.IlvManagerView) are never called.

The default implementation returns false to indicate that the basic SDM renderer does not install any listeners on views.

Since:

JViews 5.5

See Also:

addViewListeners(ilog.views.IlvManagerView), removeViewListeners(ilog.views.IlvManagerView)

addViewListeners

protected void addViewListeners(IlvManagerView view)

This method can be overridden to add view listeners on any view attached to an SDM engine.

This method is called only if needsViewListeners() returns true.

The default implementation does nothing.

Parameters:

view - The manager view.

Since:

JViews 5.5

See Also:

needsViewListeners()

removeViewListeners

protected void removeViewListeners(IlvManagerView view)

This method can be overridden to remove view listeners from any view attached to an SDM engine.

This method is called only if needsViewListeners() returns true.

The default implementation does nothing.

Parameters:

view - The manager view.

Since:

JViews 5.5

See Also:

needsViewListeners()

moveResizeNodeGraphic

protected void moveResizeNodeGraphic(IlvSDMEngine engine,
                                     Object node,
                                     IlvGraphic graphic,
                                     IlvRect newBBox,
                                     int anchor)

Move the graphic to its final position

Parameters:

engine - The SDM engine.

node - The data node that the graphic object represents.

graphic - The graphic object that to be moved and/or resized.

newBBox - An IlvRectangle initialized with the "x", "y", "width" and "height" graphic properties. The final position must be stored in this parameter. If the width or height of the rectangle are non-zero, the graphic object is moved and resized, otherwise the graphic object is only moved.

anchor - see IlvDirection for the possible values

Since:

JViews 6.0

callMoveResizeNodeGraphic

public void callMoveResizeNodeGraphic(IlvSDMEngine engine,
                                      Object node,
                                      IlvGraphic graphic,
                                      IlvRect newBBox,
                                      int anchor)

Move the graphic to its final position

Note: If the graphic object is contained inside an IlvManager, users must use the method IlvManager.applyToObject(ilog.views.IlvGraphic, ilog.views.IlvApplyObject, java.lang.Object, boolean) to call this method.

Parameters:

engine - The SDM engine.

node - The data node that the graphic object represents.

graphic - The graphic object that to be moved and/or resized.

newBBox - An IlvRectangle initialized with the "x", "y", "width" and "height" graphic properties. The final position must be stored in this parameter. If the width or height of the rectangle are non-zero, the graphic object is moved and resized, otherwise the graphic object is only moved.

anchor - see IlvDirection for the possible values

Since:

JViews 8.0

processServerAction

public boolean processServerAction(int x,
                                   int y,
                                   IlvManagerView view)

This method is called when the SDM is used on the server-side of a web application, to process an action sent by the client-side. Typically, this happens when the user clicks on the generated image of the graph in his web browser.

Subclasses of IlvSDMRenderer can decide to override this method and perform an action depending on the x/y position.

The default implementation does nothing and returns false.

Parameters:

x - The X coordinate of the point where the user clicked on the client-side, in view coordinates.

y - The y coordinate of the point where the user clicked on the client-side, in view coordinates.

view - The view used to render the graph image.

Returns:

true if the action was processed, false if the action was not processed.

Since:

JViews 6.5