Abstract class YLabel defines a set of inner interfaces which allow fine-grained control over all aspects of a label's visual representation and behavior. Custom label logic can be conveniently expressed by providing implementations for only a selection or for all of these interfaces:

Together, a set of actual implementations for these interfaces forms a so-called "configuration" that defines the look and feel of a label. Different configurations can be used to define a variety of label types.

Management of label configurations is done by static inner class YLabel.Factory. A reference to this class can be get using the NodeLabel and EdgeLabel class method shown in API Excerpt 6.23, “Static method to get the factory for configuration management”.

// Getter method in classes NodeLabel and EdgeLabel.
static YLabel.Factory getFactory()

To handle user-defined data, YLabel defines the YLabel.UserDataHandler inner interface. This interface is used to delegate all work that relates to copying or (de)serializing of all user-defined data of a label. Class SimpleUserDataHandler can be used as a default implementation for this interface. It is capable of dealing with arbitrary user-defined data objects that implement interfaces java.lang.Cloneable (for copying) and java.io.Serializable (for serialization and deserialization).

Class DefaultLabelConfiguration serves as a default implementation for all YLabel interfaces. It provides the default label behavior and can be used as a convenient base for customized configurations. Example 6.6, “Customizing the default node label configuration” shows how to create a specialized node label configuration using another YLabel.Painter implementation.

// Get the factory to register custom styles/configurations.
YLabel.Factory factory = NodeLabel.getFactory();

// Retrieve a map that holds the default NodeLabel configuration.
// The implementations contained therein can be replaced one by one in order to 
// create custom configurations...
Map implementationsMap = factory.createDefaultConfigurationMap();

// Customize the painting with a custom YLabel.Painter implementation.
implementationsMap.put(YLabel.Painter.class, new MyPainter());

// Add this configuration to the factory.
factory.addConfiguration("Bubble", implementationsMap);

Tutorial demo application YLabelConfigurationDemo.java presents in detail how a custom node label configuration is created.

The aforementioned general features are offered by abstract class YLabel. Classes NodeLabel and EdgeLabel provide further label functionality that is specific to the respective type of graph element. Figure 6.21, “Label classes hierarchy” presents the class hierarchy for the label functionality from package y.view.

Figure 6.21. Label classes hierarchy

A label naturally belongs to a specific graph element, and accordingly should be presented near this element. To control the label's position relative to its element, so-called "label models" are used.

Class NodeLabel provides a number of label models with predefined positions and additionally a "free" model, where the label's position is solely defined by an offset. Figure 6.22, “Possible node label positions” depicts all predefined positions for a node label.

Figure 6.22. Possible node label positions

It is important to note that the set of valid positions varies with the chosen model, i.e., not all possible positions are valid for each model. Table 6.4, “Valid label positions for each model” lists the sets of valid positions for each node label model.

The offset with the "free" label model is the distance vector between the upper left corners of node and label. Setting a label model and choosing one of the predefined label positions is demonstrated in Example 6.7, “Setting a node label model”. If the chosen position is not in the set of valid positions for a label model, then a default position is taken instead.

// 'nr' is of type y.view.NodeRealizer. 

// Create the label and add it to the node realizer. 
NodeLabel nl = nr.createNodeLabel();
nr.setLabel(nl);

// Set a node label model and choose one of the predefined label positions. 
// 'CORNERS' has four positions at the corners of a node, outside its bounds. 
nl.setModel(NodeLabel.CORNERS);
// 'SE' means the lower right corner. 
nl.setPosition(NodeLabel.SE);

Observe that the sets of valid positions with label models CORNERS, SANDWICH, and SIDES are proper subsets of those allowed with label model EIGHT_POS. Choosing one of these subsets explicitly restricts the number of available label positions, i.e., for the most flexibility EIGHT_POS is the best choice.

Class EdgeLabel provides several label models with predefined positions, and some "slider" models where the set of valid positions is dynamic and varies with the length of the edge path. Additionally, there is also a "free" model available, where the label's position is defined by an offset. Table 6.5, “Edge label models” lists all edge label models and shows the predefined label positions, the dynamic positions of the "slider" models, and also examples for offset positions with the "free" model.

Table 6.5. Edge label models

Model Name	Valid Positions
CENTERED	CENTER
TWO_POS	HEAD, TAIL
THREE_CENTER	SCENTR, CENTER, TCENTR
SIX_POS	SHEAD, HEAD, THEAD, STAIL, TAIL, TTAIL
CENTER_SLIDER	DYNAMIC
SIDE_SLIDER	DYNAMIC
FREE	ANYWHERE

The dynamic positions of the "slider" models are specified by a ratio value that ranges from 0.0 to 1.0. It determines the label's placement along the edge path, with increasing value meaning positions farther from the source node. The offset with the "free" label model is the distance vector between the intersection point of the first edge segment with the source node and the upper left corner of the label. Setting a label model and choosing a label position is demonstrated in Example 6.8, “Setting an edge label model”. If the chosen position is not in the set of valid positions for a label model, then a default position is taken instead.

// 'er' is of type y.view.EdgeRealizer. 

// Create the label and add it to the edge realizer. 
EdgeLabel el = er.createEdgeLabel();
er.addLabel(el);

// Set an edge label model. 'CENTER_SLIDER' has a dynamic number of label 
// positions that lie on the edge's path. 
el.setModel(EdgeLabel.CENTER_SLIDER);
el.setPosition(EdgeLabel.DYNAMIC);
// Choose a label position near the source node. 
el.setRatio(0.3);

Class Arrow renders the graphical decorations that can be placed at an edge's ends. Normally, this decoration is some kind of arrowhead that is used to indicate the edge's direction. Table 6.6, “Arrow shapes of class Arrow” depicts the predefined arrow shapes.

Note that omitting the decoration is done using another arrow shape. Arrow type NONE, which is not shown below, "renders" an empty arrow shape.

Table 6.6. Arrow shapes of class Arrow

Arrow Type	Arrow Shape
DELTA
DIAMOND
SHORT
STANDARD
WHITE_DELTA
WHITE_DIAMOND

Class Arrow supports fine-grained control of arrowhead rendering. It is possible to specify an arrowhead's distance to the border of a node, and also the position of the edge path's end relative to an arrowhead's tip.

In addition to the predefined arrow shapes it is also possible to register custom ones using the methods listed in API Excerpt 6.25, “Support for custom arrow shapes”. The most freedom defining a customized arrow(head) is provided when using graphical objects that implement interface Drawable.

// Getter and setter methods for custom arrow shapes. 
static Arrow addCustomArrow(String name, Drawable drawable)
static Arrow addCustomArrow(String name, Shape shape, Color fillColor)
static Arrow addCustomArrow(String name, Shape shape, Color fillColor, 
                            Stroke lineStroke, Color lineColor)
static Arrow getCustomArrow(String name)

// Arrow shapes using customized distance and arrow length. 
static Arrow addCustomArrow(String name, Drawable drawable, 
                            double arrowLength, double clipLength)
static Arrow addCustomArrow(String name, Shape shape, Color fillColor, 
                            Stroke lineStroke, Color lineColor, 
                            double arrowLength, double clipLength)

String getCustomName()

Class Bend is to bends (also known as control points) what classes NodeRealizer and EdgeRealizer are to nodes and edges. It handles all user interface (UI)-related aspects, i.e., it renders a bend's graphical representation, and also provides a number of features including, e.g., control of the selection state and support for hit tests.

Note that bends, i.e., control points, determine the path of an edge, but are not necessarily part of the path itself. Especially the classes BezierEdgeRealizer and SplineEdgeRealizer exhibit this difference.

The most defining characteristic of a bend is its location. API Excerpt 6.26, “Positional methods from class Bend” lists the methods that can be used to control it.

// Getter methods. 
double getX()
double getY()

// Setter methods. 
void setLocation(double newX, double newY)
void moveBy(double dx, double dy)

Class LineType is responsible for rendering the line graphic of an edge. It is used for both poly-line edges as well as curves. Table 6.7, “Line types of class LineType” shows the predefined line types. Note that the line types are available in different widths.

Table 6.7. Line types of class LineType

Constant Name	Line Type
DASHED_STYLE
DOTTED_STYLE
LINE_STYLE

Different line types can be get directly using their respective names, e.g., DASHED_1, DOTTED_2, LINE_4, etc. Alternatively, LineType also offers the static methods from API Excerpt 6.27, “Static getter methods from class LineType” to get (one of) the available line types.

static Vector availableLineTypes()
static LineType getLineType(int width, byte style)

In addition to the predefined line types it is also possible to create custom ones using the method from API Excerpt 6.28, “Support for creation of custom line types”.

static LineType createLineType(float width, 
                               int cap, int join, 
                               float miterlimit, 
                               float[] dash, float dashPhase)