com.yworks.yfiles.layout

Class LabelCandidate

java.lang.Object

com.yworks.yfiles.layout.LabelCandidate

All Implemented Interfaces:

IPlaneObject

Direct Known Subclasses:

EdgeLabelCandidate, NodeLabelCandidate

public class LabelCandidate
extends Object
implements IPlaneObject

A LabelCandidate describes one valid placement for a label considering the label model.

Generic labeling algorithms place labels according to their label model. To get valid locations for the label, the label model generates various LabelCandidates. One of these candidates will be chosen to provide the actual placement of the label.

See Also:

INodeLabelLayoutModel, IEdgeLabelLayoutModel, GenericLabeling

Constructor Summary

Constructors

Constructor and Description
LabelCandidate(YOrientedRectangle labelBox, Object param, ILabelLayout owner) Creates a new instance of LabelCandidate described by its box, model parameter and internal flag.
LabelCandidate(YOrientedRectangle labelBox, Object param, ILabelLayout owner, boolean internal) Creates a new instance of LabelCandidate described by its box, model parameter and internal flag.
LabelCandidate(YPoint pos, YDimension size, Object param, ILabelLayout owner) Creates a new instance of LabelCandidate described by location, size, model parameter and internal flag.
LabelCandidate(YPoint pos, YDimension size, Object param, ILabelLayout owner, boolean internal) Creates a new instance of LabelCandidate described by location, size, model parameter and internal flag.

Method Summary

Modifier and Type	Method and Description
YRectangle	getBoundingBox() Gets the bounding box of this candidate.
YOrientedRectangle	getBox() Gets the oriented box of this candidate.
double	getCustomProfit() Gets the custom profit for this candidate.
double	getEdgeOverlapPenalty() Gets a penalty for a candidate position that overlaps the path of an edge.
double	getHeight() Gets the height of the candidate's bounding box.
YPoint	getLocation() Gets the coordinates of the upper-left corner of the candidate's bounds.
Object	getModelParameter() Gets the model parameter that was used by the underlying model to generate this label candidate.
double	getNodeOverlapPenalty() Gets a penalty for a candidate position that overlaps the box of a node.
double	getOverlapPenalty() Gets the sum of node overlap penalty and edge overlap penalty.
ILabelLayout	getOwner() Gets the ILabelLayout for which this candidate was created.
YDimension	getSize() Gets the width and height of the candidate's bounds.
double	getWidth() Gets the width of the candidate's bounds.
double	getX() Gets the minimum x-coordinate of the candidate's bounds.
double	getY() Gets the minimum y-coordinate of the candidate's bounds.
boolean	isInternal() Gets whether or not this candidate describes an internal label.
boolean	isPropagated() Gets whether or not this candidate's box had already been chosen by the labeling algorithm.
void	propagate() Replaces the model parameter and box of the owner with the model parameter and box of this candidate.
void	setCustomProfit(double value) Sets the custom profit for this candidate.
void	setEdgeOverlapPenalty(double value) Sets a penalty for a candidate position that overlaps the path of an edge.
void	setNodeOverlapPenalty(double value) Sets a penalty for a candidate position that overlaps the box of a node.
String	toString() Returns a String representation of this LabelCandidate.

Methods inherited from class java.lang.Object

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

Constructor Detail

LabelCandidate

public LabelCandidate(YOrientedRectangle labelBox,
                      Object param,
                      ILabelLayout owner)

Creates a new instance of LabelCandidate described by its box, model parameter and internal flag.

Parameters:

labelBox - the box that specifies the candidate's size and position

param - the parameters of the label model associated with this candidate

owner - the label associated with the candidate

LabelCandidate

public LabelCandidate(YOrientedRectangle labelBox,
                      Object param,
                      ILabelLayout owner,
                      boolean internal)

Creates a new instance of LabelCandidate described by its box, model parameter and internal flag.

Parameters:

labelBox - the box that specifies the candidate's size and position

param - the parameters of the label model associated with this candidate

owner - the label associated with the candidate

internal - true if the candidate is allowed to overlap with its owner, false otherwise

LabelCandidate

public LabelCandidate(YPoint pos,
                      YDimension size,
                      Object param,
                      ILabelLayout owner)

Creates a new instance of LabelCandidate described by location, size, model parameter and internal flag.

Parameters:

pos - the location of the upper left corner of the candidate

size - the size of the candidate

param - the parameters of the label model associated with this candidate

owner - the label associated with the candidate

LabelCandidate

public LabelCandidate(YPoint pos,
                      YDimension size,
                      Object param,
                      ILabelLayout owner,
                      boolean internal)

Creates a new instance of LabelCandidate described by location, size, model parameter and internal flag.

Parameters:

pos - the location of the upper left corner of the candidate

size - the size of the candidate

param - the parameters of the label model associated with this candidate

owner - the label associated with the candidate

internal - true if the candidate is allowed to overlap with its owner, false otherwise

Method Detail

getBoundingBox

public YRectangle getBoundingBox()

Gets the bounding box of this candidate.

The bounding box describes the smallest paraxial box that contains the candidate.

Specified by:

getBoundingBox in interface IPlaneObject

Returns:

the bounding box

getBox

public YOrientedRectangle getBox()

Gets the oriented box of this candidate.

If the label is rotated, this box will be oriented accordingly.

Returns:

the size, location and orientation of the candidate

getCustomProfit

public double getCustomProfit()

Gets the custom profit for this candidate.

The profit describes the priority of this candidate with respect to other candidates. Labeling algorithms will use the profit to decide which candidate to choose.

The value is restricted to the interval [0,1], where 1 specifies the highest possible profit.

Throws:

IllegalArgumentException - if the specified value lies outside of [0,1]

The value is only considered if the labeling algorithm uses an optimization strategy.

Default Value:

The default value is 0.

Returns:

the custom profit for this candidate

See Also:

setCustomProfit(double)

getEdgeOverlapPenalty

public double getEdgeOverlapPenalty()

Gets a penalty for a candidate position that overlaps the path of an edge.

The penalty should be a factor between 0 and 1, where 0 means that an overlap is considered unimportant and 1 means that an overlap is considered severe.

Throws:

IllegalArgumentException - if the specified penalty is outside [0,1]

Default Value:

The default value is 1.

Returns:

the penalty for overlaps with edges

See Also:

setEdgeOverlapPenalty(double)

getHeight

public double getHeight()

Gets the height of the candidate's bounding box.

The bounding box is the smallest paraxial box that contains the candidate.

Returns:

the height of the candidate's bounding box

See Also:

getSize(), getBoundingBox()

getLocation

public YPoint getLocation()

Gets the coordinates of the upper-left corner of the candidate's bounds.

The bounds are the smallest paraxial box that contains the candidate.

Returns:

the coordinates of the upper-left corner

See Also:

getBoundingBox()

getModelParameter

public Object getModelParameter()

Gets the model parameter that was used by the underlying model to generate this label candidate.

Returns:

the model parameter

getNodeOverlapPenalty

public double getNodeOverlapPenalty()

Gets a penalty for a candidate position that overlaps the box of a node.

The penalty should be a factor between 0 and 1, where 0 means that an overlap is considered unimportant and 1 means that an overlap is considered severe.

Throws:

IllegalArgumentException - if the specified penalty is outside [0,1]

Default Value:

The default value is 1.

Returns:

the penalty for overlaps with nodes

See Also:

setNodeOverlapPenalty(double)

getOverlapPenalty

public double getOverlapPenalty()

Gets the sum of node overlap penalty and edge overlap penalty.

Returns:

the added penalty for edge overlaps and node overlaps

See Also:

getEdgeOverlapPenalty(), getNodeOverlapPenalty()

getOwner

public ILabelLayout getOwner()

Gets the ILabelLayout for which this candidate was created.

Returns:

the actual label to which the candidate belongs

getSize

public YDimension getSize()

Gets the width and height of the candidate's bounds.

The bounds are the smallest paraxial box that contains the candidate.

Returns:

the size of the candidate's bounds

See Also:

getBoundingBox()

getWidth

public double getWidth()

Gets the width of the candidate's bounds.

The bounds are the smallest paraxial box that contains the candidate.

Returns:

the width of the candidate's bounds

See Also:

getSize(), getBoundingBox()

getX

public double getX()

Gets the minimum x-coordinate of the candidate's bounds.

The bounds are the smallest paraxial box that contains the candidate.

Returns:

the x-coordinate of the candidate's bounds

See Also:

getLocation(), getBoundingBox()

getY

public double getY()

Gets the minimum y-coordinate of the candidate's bounds.

The bounds are the smallest paraxial box that contains the candidate.

Returns:

the y-coordinate of the candidate's bounds

See Also:

getLocation(), getBoundingBox()

isInternal

public boolean isInternal()

Gets whether or not this candidate describes an internal label.

Internal labels reside inside the boundaries of a node.

Returns:

true if the candidate represents an internal label, false otherwise

isPropagated

public boolean isPropagated()

Gets whether or not this candidate's box had already been chosen by the labeling algorithm.

If this candidate is propagated, its model parameter and box were transferred to the label.

Returns:

true if this candidate was chosen, false otherwise

See Also:

propagate()

propagate

public void propagate()

Replaces the model parameter and box of the owner with the model parameter and box of this candidate.

When this candidate is chosen to provide the placement of the label, this method transfers the model parameter and the candidate box to the ILabelLayout.

See Also:

getOwner(), getModelParameter(), getBox()

setCustomProfit

public void setCustomProfit(double value)

Sets the custom profit for this candidate.

The profit describes the priority of this candidate with respect to other candidates. Labeling algorithms will use the profit to decide which candidate to choose.

The value is restricted to the interval [0,1], where 1 specifies the highest possible profit.

Throws:

IllegalArgumentException - if the specified value lies outside of [0,1]

The value is only considered if the labeling algorithm uses an optimization strategy.

Default Value:

The default value is 0.

Parameters:

value - the custom profit for this candidate

See Also:

getCustomProfit()

setEdgeOverlapPenalty

public void setEdgeOverlapPenalty(double value)

Sets a penalty for a candidate position that overlaps the path of an edge.

The penalty should be a factor between 0 and 1, where 0 means that an overlap is considered unimportant and 1 means that an overlap is considered severe.

Throws:

IllegalArgumentException - if the specified penalty is outside [0,1]

Default Value:

The default value is 1.

Parameters:

value - the penalty for overlaps with edges

See Also:

getEdgeOverlapPenalty()

setNodeOverlapPenalty

public void setNodeOverlapPenalty(double value)

Sets a penalty for a candidate position that overlaps the box of a node.

The penalty should be a factor between 0 and 1, where 0 means that an overlap is considered unimportant and 1 means that an overlap is considered severe.

Throws:

IllegalArgumentException - if the specified penalty is outside [0,1]

Default Value:

The default value is 1.

Parameters:

value - the penalty for overlaps with nodes

See Also:

getNodeOverlapPenalty()

toString

public String toString()

Returns a String representation of this LabelCandidate.

The String contains the owning label and the coordinates of the candidate's bounds.

Overrides:

toString in class Object

Returns:

a representation of the candidate

See Also:

getOwner(), getLocation()