Class TLcdGXYHaloLabelPainter
- All Implemented Interfaces:
ILcdGXYLabelPainter
,ILcdGXYLabelPainterProvider
,ILcdGXYMultiLabelPainter
,Serializable
,Cloneable
- Direct Known Subclasses:
TLcdGXYHaloLabelPainter2
Wrapping a label painter or label painter provider
This label painter uses the Decorator design pattern to add halo support to any existingILcdGXYLabelPainter
or ILcdGXYLabelPainterProvider
implementation.
If the decorated class implements both, a cast to either
ILcdGXYLabelPainter
or ILcdGXYLabelPainterProvider
is necessary to
select the correct constructor.
When the decorated class is passed as a ILcdGXYLabelPainterProvider
, this class
must also be used as a ILcdGXYLabelPainterProvider
, which means that
getGXYLabelPainter(Object)
must be called before painting any labels.
Delegate requirements
Most of the label painters that ship with LuciadLightspeed (e.g. TLcdGXYStampLabelPainter already provide built-in support for halos. In this case, they will have methods analogous to this class to configure the halo appearance and control the use of image caching. If available, the built-in support should be preferred over the use of TLcdGXYHaloLabelPainter.
This implementation can be used with label painters/label painter providers supporting
ILcdGXYLabelPainter
or ILcdGXYMultiLabelPainter
.
If your label painter implements ILcdGXYLabelPainter2
,
we strongly recommend using TLcdGXYHaloLabelPainter2
instead.
Note that when using this label painter, it is important that the delegate label painter's
ILcdGXYLabelPainter.labelBoundsSFCT
method is correctly implemented.
Due to TLcdGXYHaloLabelPainter's use of offscreen images, anything that the delegate label painter
draws outside of the returned label bounds may be clipped away.
Halo settings
The color and thickness of the halo are configurable. Note that there is some overhead associated with drawing the halo. This overhead depends on the label thickness, so small values (1 or 2 pixels) are recommended.
To reduce the overhead associated with the halo effect, this painter can
perform image caching: the labels and their halos are drawn into an
offscreen image and cached, so that subsequent repaints do not require the
halo to be recreated. This improves performance considerably, but it is the
application's responsibility to ensure the validity of the cache. If an
object's label changes over the course of the object's lifetime, the
application must call the clearImageCache(Object)
method to
remove that object's cached image. Note that changing the halo color or
thickness automatically clears the entire image cache.
- Since:
- 7.0.17
- See Also:
-
Field Summary
Fields inherited from interface com.luciad.view.gxy.ILcdGXYLabelPainter
DEFAULT, SELECTED
-
Constructor Summary
ConstructorDescriptionTLcdGXYHaloLabelPainter
(ILcdGXYLabelPainter aLabelPainter) Creates a newTLcdGXYHaloLabelPainter
wrapping the given label painter, with default halo parameters (Color = white, thickness = 1).TLcdGXYHaloLabelPainter
(ILcdGXYLabelPainterProvider aLabelPainterProvider) Creates a newTLcdGXYHaloLabelPainterProvider
wrapping the given label painter provider, with default halo parameters (Color = white, thickness = 1).TLcdGXYHaloLabelPainter
(ILcdGXYLabelPainterProvider aLabelPainterProvider, Color aHaloColor, int aHaloThickness) Creates a newTLcdGXYHaloLabelPainterProvider
wrapping the given label painter provider, configured with the given halo color and thickness.TLcdGXYHaloLabelPainter
(ILcdGXYLabelPainter aLabelPainter, Color aHaloColor, int aHaloThickness) Creates a newTLcdGXYHaloLabelPainter
wrapping the given label painter, configured with the given halo color and thickness. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addPropertyChangeListener
(PropertyChangeListener aPropertyChangeListener) Adds aPropertyChangeListener
to this painter.void
Clears the entire label image cache.void
clearImageCache
(Object aObject) Clears the label image cache for the given object.clone()
RedefinesObject.clone
to make it public.Returns theILcdGXYLabelPainter
to which the rendering of the labels is delegated.Returns theILcdGXYLabelPainterProvider
to which the rendering of the labels is delegated.getGXYLabelPainter
(Object aObject) Always returns this label painter itself.Returns the algorithm that is used for rendering halo's.Returns the current halo color.int
Returns the current halo thickness.int
getLabelCount
(Graphics aGraphics, ILcdGXYContext aGXYContext) Returns the number of labels for the object set to this label painter.int
Returns the index of the label that is currently painted or scheduled to paint.int
Gets the index of location where to paint the label(s) of the set Object.Gets the Object this ILcdGXYLabelPainter can label.int
getPossibleLocationCount
(Graphics aGraphics) Returns the number of possible locations where thisILcdGXYLabelPainter
can paint/draw the labels of the set domainObject
.int
getSubLabelCount
(int aLabelIndex) Return the number of sublabels in a label.int
Returns the index of the sublabel to paint.boolean
Returns true if the halo effect is on, false otherwise.boolean
Returnstrue
when label image caching is enabled,false
otherwise.double
labelBoundsSFCT
(Graphics aGraphics, int aMode, ILcdGXYContext aGXYContext, Rectangle aRectangleSFCT) Calculates the bounds of the label that can be painted.void
paintLabel
(Graphics aGraphics, int aMode, ILcdGXYContext aGXYContext) Paints the label of the set Object onaGraphics
.void
removePropertyChangeListener
(PropertyChangeListener aPropertyChangeListener) Removes aPropertyChangeListener
from this painter.void
setDelegateLabelPainter
(ILcdGXYLabelPainter aDelegateLabelPainter) Sets theILcdGXYLabelPainter
to which the rendering of the labels is to be delegated.void
setDelegateLabelPainterProvider
(ILcdGXYLabelPainterProvider aDelegateLabelPainterProvider) Sets theILcdGXYLabelPainterProvider
to which the rendering of the labels is to be delegated.void
setHaloAlgorithm
(TLcdHaloAlgorithm aHaloAlgorithm) Sets the algorithm to be used for rendering halo's.void
setHaloColor
(Color aColor) Sets the color of the halo to be added around labels.void
setHaloEnabled
(boolean aHaloEnabled) Switches the halo effect on or off.void
setHaloThickness
(int aThickness) Sets the thickness (in pixels) of the halo to be added around labels.void
setLabelIndex
(int aLabelIndex) Sets the label.void
setLocationIndex
(int aLocationIndex) Sets the index of location where to paint the label(s) of the set Object.void
Sets the Object to be labeled by this ILcdGXYLabelPainter.void
setSubLabelIndex
(int aSubLabelIndex) Sets the sublabel index.void
setUseImageCache
(boolean aUseCache) Sets whether or not labels should be cached as images.
-
Constructor Details
-
TLcdGXYHaloLabelPainter
Creates a newTLcdGXYHaloLabelPainter
wrapping the given label painter, with default halo parameters (Color = white, thickness = 1). If the delegate painter is anILcdGXYLabelPainter2
, useTLcdGXYHaloLabelPainter2
instead.- Parameters:
aLabelPainter
- theILcdGXYLabelPainter
rendering the label.
-
TLcdGXYHaloLabelPainter
public TLcdGXYHaloLabelPainter(ILcdGXYLabelPainter aLabelPainter, Color aHaloColor, int aHaloThickness) Creates a newTLcdGXYHaloLabelPainter
wrapping the given label painter, configured with the given halo color and thickness. If the delegate painter is anILcdGXYLabelPainter2
, useTLcdGXYHaloLabelPainter2
instead.- Parameters:
aLabelPainter
- theILcdGXYLabelPainter
rendering the label.aHaloColor
- the halo coloraHaloThickness
- the halo thickness
-
TLcdGXYHaloLabelPainter
Creates a newTLcdGXYHaloLabelPainterProvider
wrapping the given label painter provider, with default halo parameters (Color = white, thickness = 1). If the delegate painter provider returns anILcdGXYLabelPainter2
label painters, useTLcdGXYHaloLabelPainter2
instead.Note that this constructor demands that the provider is used as a
ILcdGXYLabelPainterProvider
, which means thatgetGXYLabelPainter(Object)
must be called before using it to paint a label.- Parameters:
aLabelPainterProvider
- theILcdGXYLabelPainterProvider
rendering the label.
-
TLcdGXYHaloLabelPainter
public TLcdGXYHaloLabelPainter(ILcdGXYLabelPainterProvider aLabelPainterProvider, Color aHaloColor, int aHaloThickness) Creates a newTLcdGXYHaloLabelPainterProvider
wrapping the given label painter provider, configured with the given halo color and thickness. If the delegate painter provider is anILcdGXYLabelPainterProvider2
, useTLcdGXYHaloLabelPainter2
instead.Note that this constructor demands that the provider is used as a
ILcdGXYLabelPainterProvider
, which means thatgetGXYLabelPainter(Object)
must be called before using it to paint a label.- Parameters:
aLabelPainterProvider
- theILcdGXYLabelPainterProvider
rendering the label.aHaloColor
- the halo coloraHaloThickness
- the halo thickness
-
-
Method Details
-
isHaloEnabled
public boolean isHaloEnabled()Returns true if the halo effect is on, false otherwise.- Returns:
- true if the halo effect is on, false otherwise
- See Also:
-
setHaloEnabled
public void setHaloEnabled(boolean aHaloEnabled) Switches the halo effect on or off. If halos are not enabled, label painting is delegated directly to the wrapped label painter, without further intervention by this TLcdGXYHaloLabelPainter.- Parameters:
aHaloEnabled
- true if halos should be added, false otherwise
-
getHaloThickness
public int getHaloThickness()Returns the current halo thickness.- Returns:
- the current halo thickness
- See Also:
-
setHaloThickness
public void setHaloThickness(int aThickness) Sets the thickness (in pixels) of the halo to be added around labels. A value of 0 (the default) means that the halo effect is disabled. Note that the performance cost of adding a halo is proportional to the halo's thickness. Also note that changing this property invalidates all currently cached label images.- Parameters:
aThickness
- the new halo thickness
-
getHaloColor
Returns the current halo color.- Returns:
- the current halo color
- See Also:
-
setHaloColor
Sets the color of the halo to be added around labels. The color should be chosen such that it contrasts with the color of the labels themselves. This will ensure that the label is clearly visible on any background.Note that changing this property invalidates all currently cached label images.
- Parameters:
aColor
- the new halo color
-
setHaloAlgorithm
Sets the algorithm to be used for rendering halo's. The choice of the halo algorithm may have a major impact on the overall performance of this painter. SeeTLcdHaloAlgorithm
for more information on the available algorithms.- Parameters:
aHaloAlgorithm
- the algorithm to be used for rendering halo's.- See Also:
-
getHaloAlgorithm
Returns the algorithm that is used for rendering halo's.- Returns:
- the algorithm that is used for rendering halo's.
- See Also:
-
isUseImageCache
public boolean isUseImageCache()Returnstrue
when label image caching is enabled,false
otherwise.- Returns:
true
when label image caching is enabled,false
otherwise
-
setUseImageCache
public void setUseImageCache(boolean aUseCache) Sets whether or not labels should be cached as images. Enabling the cache will improve painting performance significantly, as labels will need to be rendered only once. Two caveats apply, however:- Caching requires more memory (one image for each label).
- A cached image must be removed if its corresponding label changes.
This can happen, for instance, if the label displays a dynamically
changing property of an object. A typical solution is to create an
ILcdModelListener
that removes an object from the image cache whenever that object changes.
- Parameters:
aUseCache
- specifies whether image caching should be enabled- See Also:
-
clearImageCache
public void clearImageCache()Clears the entire label image cache. To remove a single label from the cache, useclearImageCache(Object)
.- See Also:
-
clearImageCache
Clears the label image cache for the given object. The next time this object is painted, a new image will be created and cached for it. To remove all cached images in one go, useclearImageCache()
.- Parameters:
aObject
- the object for which the cache to be cleared.- See Also:
-
getDelegateLabelPainter
Returns theILcdGXYLabelPainter
to which the rendering of the labels is delegated.- Returns:
- the
ILcdGXYLabelPainter
to which the rendering of the labels is delegated.
-
setDelegateLabelPainter
Sets theILcdGXYLabelPainter
to which the rendering of the labels is to be delegated. If the delegate painter is anILcdGXYLabelPainter2
, useTLcdGXYHaloLabelPainter2
instead.- Parameters:
aDelegateLabelPainter
- theILcdGXYLabelPainter
to which the rendering of the labels is delegated.
-
getDelegateLabelPainterProvider
Returns theILcdGXYLabelPainterProvider
to which the rendering of the labels is delegated.- Returns:
- the
ILcdGXYLabelPainterProvider
to which the rendering of the labels is delegated.
-
setDelegateLabelPainterProvider
public void setDelegateLabelPainterProvider(ILcdGXYLabelPainterProvider aDelegateLabelPainterProvider) Sets theILcdGXYLabelPainterProvider
to which the rendering of the labels is to be delegated. If the delegate painter provider returnsILcdGXYLabelPainter2
instances, useTLcdGXYHaloLabelPainter2
instead.- Parameters:
aDelegateLabelPainterProvider
- theILcdGXYLabelPainterProvider
to which the rendering of the labels is delegated.
-
addPropertyChangeListener
Adds aPropertyChangeListener
to this painter.- Parameters:
aPropertyChangeListener
- the receiver of property change events generated by this object- See Also:
-
removePropertyChangeListener
Removes aPropertyChangeListener
from this painter.- Parameters:
aPropertyChangeListener
- the listener to be removed- See Also:
-
getGXYLabelPainter
Always returns this label painter itself.- Specified by:
getGXYLabelPainter
in interfaceILcdGXYLabelPainterProvider
- Parameters:
aObject
- the object for which a label painter is requested- Returns:
- this label painter itself
-
setObject
Description copied from interface:ILcdGXYLabelPainter
Sets the Object to be labeled by this ILcdGXYLabelPainter.- Specified by:
setObject
in interfaceILcdGXYLabelPainter
- Parameters:
aObject
- The object to be labeled.- See Also:
-
getObject
Description copied from interface:ILcdGXYLabelPainter
Gets the Object this ILcdGXYLabelPainter can label.- Specified by:
getObject
in interfaceILcdGXYLabelPainter
- Returns:
- the Object this ILcdGXYLabelPainter can label.
- See Also:
-
setLocationIndex
public void setLocationIndex(int aLocationIndex) Description copied from interface:ILcdGXYLabelPainter
Sets the index of location where to paint the label(s) of the set Object.- Specified by:
setLocationIndex
in interfaceILcdGXYLabelPainter
- Parameters:
aLocationIndex
- the index of the location. Must be between 0 and getPossibleLocationCount() - 1.- See Also:
-
getLocationIndex
public int getLocationIndex()Description copied from interface:ILcdGXYLabelPainter
Gets the index of location where to paint the label(s) of the set Object.- Specified by:
getLocationIndex
in interfaceILcdGXYLabelPainter
- Returns:
- the index of the position. Must be between 0 and getPossibleLocationCount() - 1.
- See Also:
-
paintLabel
Description copied from interface:ILcdGXYLabelPainter
Paints the label of the set Object on
aGraphics
.aGXYContext
should contain theILcdGXYView
for which the label is painted andILcdGXYLayer
to which the object belongsThe implementation of this method shall define how to paint the label of the set Object in the given mode, considering
aGXYContext
and the possible locationsaLocationIndex
(of multiple alternatives).The domain
Object
of the label to be painted and the location index should be set before calling this method using thesetObject
andsetLocationIndex
methods respectively.- Specified by:
paintLabel
in interfaceILcdGXYLabelPainter
- Parameters:
aGraphics
- theGraphics
instance on which to paint.aMode
- a combination of ILcdGXYLabelPainter.DEFAULT and ILcdGXYLabelPainter.SELECTED.aGXYContext
- theILcdGXYContext
in which the label painting has to be performed.- See Also:
-
getPossibleLocationCount
Description copied from interface:ILcdGXYLabelPainter
Returns the number of possible locations where thisILcdGXYLabelPainter
can paint/draw the labels of the set domainObject
.The domain
Object
for which the location count is retrieved should be set before calling this method using theILcdGXYLabelPainter.setObject(java.lang.Object)
method.- Specified by:
getPossibleLocationCount
in interfaceILcdGXYLabelPainter
- Parameters:
aGraphics
- the Graphics the label will be painted on.- Returns:
- the number of possible locations where this
ILcdGXYLabelPainter
can paint/draw the labels of the set Object. - See Also:
-
labelBoundsSFCT
public double labelBoundsSFCT(Graphics aGraphics, int aMode, ILcdGXYContext aGXYContext, Rectangle aRectangleSFCT) throws TLcdNoBoundsException Description copied from interface:ILcdGXYLabelPainter
Calculates the bounds of the label that can be painted. The bounds are set as a side effect in
aRectangleSFCT
, the orientation ofaRectangleSFCT
is returned as an angle.The bounds represent the upper left point of the label, and a width and a height. The rotation value represents the rotation of the label bounds around the upper left point.
The object for which the bounds are retrieved and the location index of the label should be set before calling this method using the
ILcdGXYLabelPainter.setObject(java.lang.Object)
andILcdGXYLabelPainter.setLocationIndex(int)
methods respectively.- Specified by:
labelBoundsSFCT
in interfaceILcdGXYLabelPainter
- Parameters:
aGraphics
- theaGraphics
to consider.aMode
- the representation mode of the label.aGXYContext
- theILcdGXYContext
the drawing depends on.aRectangleSFCT
- theRectangle
containing the bounds of the label in view / graphics coordinates as side effect.- Returns:
- the angle orientation of the rectangle around the labels in RADIANs, clockwise, 0 at 3 o'clock.
- Throws:
TLcdNoBoundsException
- if the Object doesn't have any valid bounds, e.g. if it is always invisible in the current projection.- See Also:
-
clone
Description copied from interface:ILcdGXYLabelPainter
RedefinesObject.clone
to make it public.- Specified by:
clone
in interfaceILcdGXYLabelPainter
- Specified by:
clone
in interfaceILcdGXYLabelPainterProvider
- Overrides:
clone
in classObject
-
setLabelIndex
public void setLabelIndex(int aLabelIndex) Sets the label. The results of any subsequent method calls to
ILcdGXYLabelPainter.paintLabel(java.awt.Graphics, int, com.luciad.view.gxy.ILcdGXYContext)
andILcdGXYLabelPainter.labelBoundsSFCT(java.awt.Graphics, int, com.luciad.view.gxy.ILcdGXYContext, java.awt.Rectangle)
etc. will apply to the label and sublabel indicated by this label index.This implementation calls the delegate label painter if it implements ILcdGXYMultiLabelPainter.
- Specified by:
setLabelIndex
in interfaceILcdGXYMultiLabelPainter
- Parameters:
aLabelIndex
- The label index. This should be larger than or equal to0
and less than the resultILcdGXYMultiLabelPainter.getLabelCount(java.awt.Graphics, com.luciad.view.gxy.ILcdGXYContext)
.- See Also:
-
getLabelIndex
public int getLabelIndex()Returns the index of the label that is currently painted or scheduled to paint.This implementation calls the delegate label painter if it implements ILcdGXYMultiLabelPainter, else it returns 0;
- Specified by:
getLabelIndex
in interfaceILcdGXYMultiLabelPainter
- Returns:
- the index of the label that is currently painted or scheduled to paint.
- See Also:
-
getLabelCount
Returns the number of labels for the object set to this label painter.
Note: when returning multiple (moveable) labels for the same object, it might be useful to useTLcdGXYEditControllerModel2.EDIT_WHAT_FIRST_TOUCHED_LABEL
to avoid that a mouse drag moves them all together.This implementation calls the delegate label painter if it implements ILcdGXYMultiLabelPainter, else it returns 1;
- Specified by:
getLabelCount
in interfaceILcdGXYMultiLabelPainter
- Parameters:
aGraphics
- The Graphics currently painting onaGXYContext
- The ILcdGXYContext currently valid- Returns:
- The number of label for the given object.
-
getSubLabelIndex
public int getSubLabelIndex()Returns the index of the sublabel to paint.This implementation calls the delegate label painter if it implements ILcdGXYMultiLabelPainter, else it returns 0.
- Specified by:
getSubLabelIndex
in interfaceILcdGXYMultiLabelPainter
- Returns:
- the index of the sublabel to paint.
- See Also:
-
setSubLabelIndex
public void setSubLabelIndex(int aSubLabelIndex) Sets the sublabel index. The results of any subsequent method calls toILcdGXYLabelPainter.paintLabel(java.awt.Graphics, int, com.luciad.view.gxy.ILcdGXYContext)
andILcdGXYLabelPainter.labelBoundsSFCT(java.awt.Graphics, int, com.luciad.view.gxy.ILcdGXYContext, java.awt.Rectangle)
etc. will apply to the label and sublabel indicated by this sublabel index.This implementation calls the delegate label painter if it implements ILcdGXYMultiLabelPainter.
- Specified by:
setSubLabelIndex
in interfaceILcdGXYMultiLabelPainter
- Parameters:
aSubLabelIndex
- The sub label index. This should be larger than or equal to0
and less than the resultILcdGXYMultiLabelPainter.getSubLabelCount(int)
.- See Also:
-
getSubLabelCount
public int getSubLabelCount(int aLabelIndex) Return the number of sublabels in a label. The value should be 1 or higher.This implementation calls the delegate label painter if it implements ILcdGXYMultiLabelPainter, else it returns 1.
- Specified by:
getSubLabelCount
in interfaceILcdGXYMultiLabelPainter
- Parameters:
aLabelIndex
- the index of the label.- Returns:
- The number of sublabels of the label with the given index.
-