public class IlvLegendRenderer extends IlvInteractorRenderer
IlvLegendRenderer
is a
filtering renderer that draws a legend on top
of the graph, or in a separate window.
The legend consists of "samples" (or copies) of some of the objects (nodes or links) of the data. To determine which objects should be displayed, you specify an "index" property. The legend renderer examines the value of the index property for every object of the SDM, and collects the graphic objects that correspond to the different values of the property.
For example, if the links of your data links have a "bandwidth" property, you could use "bandwidth" as the index property. The legend renderer would then show copies of the graphic links for different values of the "bandwidth" property. If you configured a style sheet to set the thickness of the links according to the bandwidth, you would see the different thicknesses in the legend.
The index property can be defined in the data model, or in the style sheet. For example, if you want the legend to show samples for different bandwidth intervals, you can define the following CSS rules:
SDM { Legend : "true"; } Legend { indexProperty : "bandwidthLegend"; } link[bandwidth > 100] { bandwidthLegend : "thick"; } link[bandwidth <= 100] { bandwidthLegend : "thin"; }The legend will show two samples of links, one whose bandwidth is greater that
100
and one whose bandwidth
is less than 100
.
The legend can contain several columns, corresponding
to several index properties. See setIndexProperty(java.lang.String)
,
setTitle(java.lang.String)
.
Many aspects of the graphic look of the legend can be customized: margins, colors, and so on.
The samples displayed in the legend can also be customized
separately in the style sheet, using the legend
pseudo-class. For example, if you use curved links in the SDM view,
you will not want the legend to contain curved links because it
does not look nice. For this, you can define a rule such as:
link:legend { curved : "false"; }
The legend can be inlaid inside the SDM view, or it can be displayed in a separate window. When it is inlaid, the legend can be moved around so that it does not disturb the user.
The legend can display small checkboxes that let the user hide or show all the objects represented by the legend element.
Modifier and Type | Class and Description |
---|---|
static class |
IlvLegendRenderer.LegendLayer
This inner class is public only so that it can be saved to IVL files.
|
_interactor
_renderer
PSEUDOCLASS_PREFIX
Constructor and Description |
---|
IlvLegendRenderer()
Creates a new legend renderer with a
null
filtered renderer. |
IlvLegendRenderer(IlvSDMRenderer renderer)
Creates a new legend renderer for a specified
filtered renderer.
|
Modifier and Type | Method and Description |
---|---|
protected boolean |
acceptShortcut(IlvSDMEngine engine,
IlvManagerView view,
InputEvent event)
Returns
true if the event is a mouse event
occurring inside the legend, to allow users to interact
with the legend even if a view interactor is active. |
protected void |
addViewListeners(IlvManagerView view)
Adds the listeners that adjust the legend when the view
is resized or transformed.
|
boolean |
areCheckBoxesVisible()
Returns the flag specifying whether the legend
should display check boxes that lets the user
hide and show the objects described by a specific
legend entry.
|
boolean |
areLabelsZoomable()
Returns the flag specifying whether the legend
should use zoomable labels.
|
IlvRect |
computeBBox(IlvSDMEngine engine,
IlvManagerView view,
IlvTransformer t)
Computes the rectangle that contains all
the graphic objects of the manager for a given view.
|
void |
customize(IlvSDMEngine engine,
Object object,
IlvGraphic g,
String[] pseudoClasses)
This method simply calls the
customize method
of the filtered renderer. |
Color |
getBackground()
Gets the background color of the legend box.
|
Color |
getForeground()
Gets the foreground color of the legend box.
|
String |
getIndexProperty()
Returns the name of the object properties to use as indexes.
|
int |
getInsideMargin()
Returns the margin that will be kept between
the legend elements and the legend sides.
|
Font |
getLabelFont()
Gets the font of the legend labels.
|
int |
getLayer()
Returns the layer of the legend box.
|
IlvManagerView |
getLegendView()
Returns the view in which the legend is drawn.
|
double[] |
getLinksLength()
Returns the lengths of links in the legend box.
|
double[] |
getLinksWidth()
Returns the widths of links in the legend box.
|
int |
getMaxEntries()
Returns the maximum number of entries in each column of the legend box.
|
int |
getOutsideMargin()
Returns the margin that will be kept between
the legend box and the view sides.
|
String |
getParameter()
This method calls
getIndexProperty() . |
int |
getPosition()
Returns the position of the legend box.
|
int |
getScrollDelay()
Returns the delay after which the legend reappears
when the view has been scrolled.
|
int |
getSpacing()
Returns the spacing between the elements inside the legend box.
|
String |
getTitle()
Returns the titles of the legends.
|
Font |
getTitleFont()
Gets the font of the legend titles.
|
double |
getXOffset()
Returns the horizontal offset of the legend box.
|
double |
getYOffset()
Returns the vertical offset of the legend box.
|
boolean |
isIncludingLegendInBBox()
Returns
true if the legend is to be included in the bounding
rectangle of the grapher, or false otherwise. |
boolean |
isInlaid()
Returns the flag specifying whether the legend
should be contained in the same grapher as
the SDM, or if it should be placed in
an independent grapher displayed in a
separate frame.
|
boolean |
isLegendVisible()
Returns
true if the legend is visible,
or false if the legend is not visible. |
boolean |
isLegendZooming()
Returns
true if the items displayed in the legend zoom
when the SDM view is zoomed, or false if the size of the
legend items stays fixed. |
boolean |
isSortingEntries()
Returns the flag specifying whether the entries should
be sorted or not.
|
boolean |
isUpdatingOnPropertyChange()
Returns
true if the legend is updated when properties
of objects are changed dynamically. |
void |
linkGraphicAdded(IlvSDMEngine engine,
Object link,
IlvGraphic graphic,
boolean redraw)
Looks at the index properties for the specified object,
and creates an entry for the object in the legend if needed.
|
protected boolean |
needsViewListeners()
Returns
true , because this renderer needs to install
listeners to be notified of transformer changes. |
void |
nodeGraphicAdded(IlvSDMEngine engine,
Object node,
IlvGraphic graphic,
boolean redraw)
Looks at the index properties for the specified object,
and creates an entry for the object in the legend if needed.
|
void |
prepareRendering(IlvSDMEngine engine)
Initializes the legend.
|
boolean |
processServerAction(int x,
int y,
IlvManagerView view)
Processes clicks in the legend's check boxes from the client-side
of a web application.
|
void |
removeAll(IlvSDMEngine engine)
Clears the legend.
|
protected void |
removeViewListeners(IlvManagerView view)
Removes the listeners that adjust the legend when the view
is resized or transformed.
|
void |
renderingDone(IlvSDMEngine engine)
Updates the layout of the legend.
|
void |
setBackground(Color background)
Sets the background color of the legend box.
|
void |
setCheckBoxesVisible(boolean checkBoxesVisible)
Sets the flag specifying whether the legend
should display check boxes that let the user
hide and show the objects described by a specific
legend entry.
|
void |
setForeground(Color foreground)
Sets the foreground color of the legend box.
|
void |
setIncludingLegendInBBox(boolean include)
Specifies whether the legend should be included in the bounding
rectangle of the grapher.
|
void |
setIndexProperty(String indexProperty)
Sets the name of the object properties to use as indexes.
|
void |
setInlaid(boolean inlaid)
Sets the flag specifying whether the legend
should be contained in the same grapher as
the SDM, or if it should be placed in
an independent grapher displayed in a
separate frame.
|
void |
setInsideMargin(int insideMargin)
Sets the margin that will be kept between
the legend elements and the legend sides.
|
void |
setLabelFont(Font labelFont)
Sets the font of the legend labels.
|
void |
setLabelsZoomable(boolean labelsZoomable)
Sets the flag specifying whether the legend
should use zoomable labels.
|
void |
setLayer(int layer)
Sets the index of the manager layer in which the legend box
will be placed.
|
void |
setLegendVisible(boolean visible)
Makes the legend visible or invisible.
|
void |
setLegendZooming(boolean zooming)
Specifies whether the items displayed in the legend should zoom
when the SDM view is zoomed, or if the size of the legend items
should stay fixed.
|
void |
setLinksLength(double[] linksLength)
Sets the lengths of links in the legend box.
|
void |
setLinksWidth(double[] linksWidth)
Sets the widths of links in the legend box.
|
void |
setMaxEntries(int maxEntries)
Sets the maximum number of entries in each column of the legend box.
|
void |
setOutsideMargin(int outsideMargin)
Sets the margin that will be kept between
the legend box and the view sides.
|
void |
setParameter(String parameter)
This method calls
setIndexProperty(java.lang.String) . |
void |
setPosition(int position)
Sets the position of the legend box with respect
to the SDM view.
|
void |
setScrollDelay(int delay)
Sets the delay after which the legend reappears
when the view has been scrolled.
|
void |
setSortingEntries(boolean sort)
Sets the flag specifying whether the entries should
be sorted or not.
|
void |
setSpacing(int spacing)
Sets the spacing between the elements inside the legend box.
|
void |
setTitle(String title)
Sets the titles of the legends.
|
void |
setTitleFont(Font titleFont)
Sets the font of the legend titles.
|
void |
setUpdatingOnPropertyChange(boolean update)
Specifies if the legend must be updated when properties
of objects are changed dynamically.
|
void |
setXOffset(double xOffset)
Sets the horizontal offset of the legend box.
|
void |
setYOffset(double yOffset)
Sets the vertical offset of the legend box.
|
void |
updateLegend(IlvSDMEngine engine)
Updates the legend according to the contents of the SDM view.
|
acceptInteractor, getInteractor, isProcessMouseMoveEvents, isShorcutEnabled, isShortcutEnabled, propertiesChanged, setInteractor, setProcessMouseMoveEvents, setShorcutEnabled, setShortcutEnabled
addLinkGraphic, addNodeGraphic, createLinkGraphic, createNodeGraphic, getEncapsulatedGraphic, getFilteredRenderer, getGraphicProperty, getLinkConnectionRectangle, moveResizeNodeGraphic, nodeGraphicBBoxChanged, removeLinkGraphic, removeNodeGraphic, setFilteredRenderer, updateObjectProperties
callMoveResizeNodeGraphic, convert, convert, getAlias, getAuxiliaryBean, getAuxiliaryBeans, getEngine, getLinkConnectionRectangle, getLocation, propertyChanged, setAlias, setEngine, setLayerName
public IlvLegendRenderer(IlvSDMRenderer renderer)
renderer
- The filtered renderer.public IlvLegendRenderer()
null
filtered renderer.public void setIndexProperty(String indexProperty)
indexProperty
- The index properties, separated by commas.public String getIndexProperty()
public void setParameter(String parameter)
setIndexProperty(java.lang.String)
.setParameter
in class IlvInteractorRenderer
parameter
- The value of the parameter.public String getParameter()
getIndexProperty()
.getParameter
in class IlvInteractorRenderer
IlvInteractorRenderer.setInteractor(java.lang.String)
public void setTitle(String title)
title
- A string containing a list of comma-separated
labels to use as the legend titles. The number of elements
in this list should match the number of index properties.setIndexProperty(java.lang.String)
public String getTitle()
public void setLayer(int layer)
layer
- The layer index.public int getLayer()
public void setPosition(int position)
position
- A position. See IlvDirection
for the possible value.setOutsideMargin(int)
,
setXOffset(double)
,
setYOffset(double)
public int getPosition()
setPosition(int)
public void setXOffset(double xOffset)
setPosition(int)
;
the X and Y offsets are then applied.xOffset
- An offset in view coordinates.public double getXOffset()
setXOffset(double)
public void setYOffset(double yOffset)
setPosition(int)
;
the X and Y offsets are then applied.yOffset
- An offset in view coordinates.public double getYOffset()
setYOffset(double)
public void setSpacing(int spacing)
spacing
- The spacing in pixels.public int getSpacing()
public void setOutsideMargin(int outsideMargin)
outsideMargin
- The margin in pixels.public int getOutsideMargin()
public void setInsideMargin(int insideMargin)
insideMargin
- The margin in pixels.public int getInsideMargin()
public void setLinksLength(double[] linksLength)
linksLength
- An array of doubles. The length of
the array must match the number of index properties
specified by setIndexProperty(java.lang.String)
.public double[] getLinksLength()
setLinksLength(double[])
public void setLinksWidth(double[] linksWidth)
linksWidth
- An array of doubles. The width of
the array must match the number of index properties
specified by setIndexProperty(java.lang.String)
.public double[] getLinksWidth()
setLinksWidth(double[])
public void setMaxEntries(int maxEntries)
maxEntries
- The maximum number of entries. The default is 10
.public int getMaxEntries()
public void setBackground(Color background)
background
- The background color.public Color getBackground()
public void setForeground(Color foreground)
foreground
- The foreground color.public Color getForeground()
public void setLabelFont(Font labelFont)
labelFont
- The new label font.public Font getLabelFont()
public void setTitleFont(Font titleFont)
titleFont
- The new title font.public Font getTitleFont()
public void setInlaid(boolean inlaid)
inlaid
- If true
, the legend
is placed in the same grapher as the rendered
data. If false
, the legend
is placed in a separate grapher, which is
displayed in a separate frame.public boolean isInlaid()
setInlaid(boolean)
public void setLabelsZoomable(boolean labelsZoomable)
labelsZoomable
- If true
, the legend
labels will be zoomable. Otherwise, they will have a fixed size.public boolean areLabelsZoomable()
setLabelsZoomable(boolean)
public void setCheckBoxesVisible(boolean checkBoxesVisible)
checkBoxesVisible
- If true
, the check
boxes are visible.public boolean areCheckBoxesVisible()
setCheckBoxesVisible(boolean)
public void setSortingEntries(boolean sort)
sort
- If true
, the entries will be sorted
(in ascending lexicographic order) otherwise they will appear in the same
order as in the data model.public boolean isSortingEntries()
public void setLegendZooming(boolean zooming)
Zooming the legend items ensures that the objects have exactly the same size in the legend and in the actual graph. This is desirable when the graph contains nodes of different sizes according to a property (for instance, nodes that represent cities may have different sizes according to the population of the city). In that case, it is better if the size of the legend items is the same as in the actual graph.
On the other hand, zooming legend items can lead to weird effects (for instance, the legend may become huge and cover all the graph, or the items may become invisible). So, if the size of the items is not particularly important to understand the display, it is usually better not to zoom the legend together with the view.
By default, the items zoom together with the view if the legend is inlaid, and the items do not zoom if the legend is not inlaid (for compatibility with the previous version of Rogue Wave JViews).
zooming
- If true
, the items displayed in the
legend are zoomed so that they always have the same size as the
actual objects of the graph. If false
, the size of
the items does not change when the view is zoomed or unzoomed.public boolean isLegendZooming()
true
if the items displayed in the legend zoom
when the SDM view is zoomed, or false
if the size of the
legend items stays fixed.setLegendZooming(boolean)
public void setLegendVisible(boolean visible)
This method lets you control the visibility of the legend by API.
visible
- Controls the visibility of the legend.public boolean isLegendVisible()
true
if the legend is visible,
or false
if the legend is not visible.setLegendVisible(boolean)
public void setScrollDelay(int delay)
When the legend is inlaid, it is hidden during scroll operations, and it reappears, after a short delay, at the end of the scroll.
You can use this method if you notice that the legend reappears unexpectedly while you scroll the SDM view, which produces undesired visual effects and slows down the interaction. The default delay is 200 milliseconds; specify a longer delay to prevent the legend from reappearing too quickly.
delay
- The amount of delay, in milliseconds.public int getScrollDelay()
setScrollDelay(int)
public IlvManagerView getLegendView()
null
if the
legend is in "inlaid" mode.public void removeAll(IlvSDMEngine engine)
removeAll
in class IlvFilterSDMRenderer
engine
- The SDM engine.public void prepareRendering(IlvSDMEngine engine)
prepareRendering
in class IlvFilterSDMRenderer
engine
- The SDM engine.protected boolean needsViewListeners()
true
, because this renderer needs to install
listeners to be notified of transformer changes.needsViewListeners
in class IlvInteractorRenderer
IlvSDMRenderer.addViewListeners(ilog.views.IlvManagerView)
,
IlvSDMRenderer.removeViewListeners(ilog.views.IlvManagerView)
protected void addViewListeners(IlvManagerView view)
addViewListeners
in class IlvInteractorRenderer
view
- The manager view.IlvSDMRenderer.needsViewListeners()
protected void removeViewListeners(IlvManagerView view)
removeViewListeners
in class IlvInteractorRenderer
view
- The manager view.IlvSDMRenderer.needsViewListeners()
public void nodeGraphicAdded(IlvSDMEngine engine, Object node, IlvGraphic graphic, boolean redraw)
nodeGraphicAdded
in class IlvInteractorRenderer
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.IlvSDMRenderer.addNodeGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, boolean)
public void linkGraphicAdded(IlvSDMEngine engine, Object link, IlvGraphic graphic, boolean redraw)
linkGraphicAdded
in class IlvInteractorRenderer
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.IlvSDMRenderer.addLinkGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, boolean)
public void setUpdatingOnPropertyChange(boolean update)
Note: This option may be time consuming, because all the objects of the data model have to be re-scanned to update the legend.
update
- If true
, the legend will be updated
every time a property of an object of the SDM data model is changed
dynamically. If false
, the legend will only be updated
the first time the data model is rendered, and every time an
object is added to the model.public boolean isUpdatingOnPropertyChange()
true
if the legend is updated when properties
of objects are changed dynamically.setUpdatingOnPropertyChange(boolean)
public void updateLegend(IlvSDMEngine engine)
setUpdatingOnPropertyChange(true)
was called, but an application may also call it directly to
update the legend at any time.engine
- The SDM engine.public void customize(IlvSDMEngine engine, Object object, IlvGraphic g, String[] pseudoClasses)
customize
method
of the filtered renderer.customize
in class IlvFilterSDMRenderer
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
.public void renderingDone(IlvSDMEngine engine)
renderingDone
in class IlvFilterSDMRenderer
engine
- The SDM engine.protected boolean acceptShortcut(IlvSDMEngine engine, IlvManagerView view, InputEvent event)
true
if the event is a mouse event
occurring inside the legend, to allow users to interact
with the legend even if a view interactor is active.acceptShortcut
in class IlvInteractorRenderer
engine
- The SDM engine attached to the reference view
in which the event occurred.view
- The reference view.event
- The event received by the manager view while
a view interactor was active.public IlvRect computeBBox(IlvSDMEngine engine, IlvManagerView view, IlvTransformer t)
This method is overridden to make sure that the inlaid legend is not taken into account for the computation of the bounding rectangle.
computeBBox
in class IlvFilterSDMRenderer
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.public void setIncludingLegendInBBox(boolean include)
ilog.views.sdm.ui.print
package).include
- If true
, the legend is included in the
bounding rectangle of the grapher. If false
, the legend
is not included.public boolean isIncludingLegendInBBox()
true
if the legend is to be included in the bounding
rectangle of the grapher, or false
otherwise.setIncludingLegendInBBox(boolean)
public boolean processServerAction(int x, int y, IlvManagerView view)
processServerAction
in class IlvFilterSDMRenderer
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.true
if the action was processed,
false
if the action was not processed.© Copyright Rogue Wave Software, Inc. 1997, 2018. All Rights Reserved.