Overview
TTreeConnection is a component that draws single or multi-line segments between nodes in a tree. Each connection is a full component with properties, methods, and events for customizing the appearance and behavior of lines connecting nodes.
Class Hierarchy
TComponent
└─ TCustomTreeElement
└─ TTreeConnection
Key Features
- Multiple connection styles (auto, line, sides, curve)
- Customizable arrows at start and end points
- Multi-point connections
- Text labels on connections
- Border styling and colors
- Interactive selection and editing
- Automatic and manual positioning
Properties
Connected Nodes
The source node of the connection.
The destination node of the connection.
Connection Style
Style
TTreeConnectionStyle
default:"csAuto"
Defines how the connection is drawn:
csAuto - Automatic style determined by ChildManagercsLine - Direct straight linecsSides - Line with right angles (sides)csCurve - Bezier curvecsInvertedSides - Inverted sides style
Visual Appearance
Pen used to draw the connection line. Default is gray with small dots.TTreeConnectionPen defaults:
- Color:
clGray
- SmallDots:
True
- Style:
psDot
Additional formatting options for the connection background.
Arrows
Arrow displayed at the start (From) point of the connection.Properties:
Style - Arrow style (default: casNone)Size - Arrow size in pixelsBorder - Arrow border penBrush - Arrow fill brushBackColor - Arrow background color
Arrow Styles:
casNone - No arrowcasSolid - Filled solid arrowcasLines - Line arrowcasSquare - Square arrowcasCircle - Circle arrowcasDiamond - Diamond arrow
Arrow displayed at the end (To) point of the connection. Default style is casSolid.
Connection Points
Collection of connection points that define the path of the connection.Point Styles:
cpsAutoFrom - Automatic position on From nodecpsAutoTo - Automatic position on To nodecpsFromPercent - Percentage offset from From nodecpsToPercent - Percentage offset from To nodecpsFromRel - Relative pixels from From nodecpsToRel - Relative pixels from To nodecpsPrevious - Relative to previous pointcpsNext - Relative to next pointcpsFixed - Fixed XY position
Text
Text to display along the connection line.
Font for connection text.
Other
Mouse cursor when hovering over the connection.
Reference to the parent Tree component.
Methods
Drawing
Draws the connection.Returns: True if connection was drawn Draws edit handles when connection is selected.procedure DrawHandles; override;
Draws text on the connection.procedure DrawText(Angle: Integer);
Hit Testing
Tests if coordinates are on the connection line.function Clicked(x, y: Integer): Boolean;
x, y - Coordinates to test
Returns: True if point is on the connection Returns which line segment was clicked.function ClickedSegment(x, y: Integer): Integer;
Geometry
Returns the bounding rectangle of the connection.function GetBounds: TRect;
Returns True if connection is visible.function Visible: Boolean;
Other
Copies properties from another connection.procedure Assign(Source: TPersistent); override;
Connection Points API
The Points property provides methods to manipulate connection points:
Adding Points
Adds a new point to the connection.// Add point from TPoint
function Add(const P: TPoint): Integer; overload;
// Add point from coordinates
function Add(Ax, Ay: Integer): Integer; overload;
// Add point with style
function Add(AXStyle: TConnectionPointStyle; Ax: Integer;
AYStyle: TConnectionPointStyle; Ay: Integer): Integer; overload;
Adds a point relative to the previous point.function AddFromPrevious(XOffset, YOffset: Integer): Integer;
Modifying Points
Moves a point by offset.procedure Move(Index: Integer; DeltaX, DeltaY: Integer);
Inserts a point at specific index.procedure Insert(Index: Integer; x, y: Integer);
Removes a point.procedure Delete(Index: Integer);
Returns the number of points. Finds which point was clicked.function Clicked(x, y: Integer): Integer;
Changes the X coordinate style of a point.procedure ChangeXStyle(Index: Integer; AStyle: TConnectionPointStyle);
Changes the Y coordinate style of a point.procedure ChangeYStyle(Index: Integer; AStyle: TConnectionPointStyle);
Usage Examples
Creating a Simple Connection
var
Node1, Node2: TTreeNodeShape;
Conn: TTreeConnection;
begin
Node1 := Tree1.Add(100, 100, 'Start', nil);
Node2 := Tree1.Add(300, 200, 'End', nil);
// Create connection
Conn := Node1.AddConnection(Node2);
end;
Customizing Connection Appearance
var
Conn: TTreeConnection;
begin
Conn := Node1.AddConnection(Node2);
// Line style
Conn.Style := csLine;
Conn.Border.Color := clBlue;
Conn.Border.Width := 2;
Conn.Border.Style := psSolid;
// Arrows
Conn.ArrowFrom.Style := casSolid;
Conn.ArrowFrom.Size := 8;
Conn.ArrowFrom.Brush.Color := clBlue;
Conn.ArrowTo.Style := casDiamond;
Conn.ArrowTo.Size := 10;
Conn.ArrowTo.Border.Color := clRed;
end;
Adding Text to Connection
var
Conn: TTreeConnection;
begin
Conn := Node1.AddConnection(Node2);
Conn.Text.Add('Connection Label');
Conn.Font.Size := 10;
Conn.Font.Style := [fsBold];
Conn.Font.Color := clNavy;
end;
Creating Multi-Point Connection
var
Conn: TTreeConnection;
begin
Conn := Node1.AddConnection(Node2);
// Set manual style
Conn.Style := csLine;
// Add intermediate points
Conn.Points.Clear;
Conn.Points.Add(cpsAutoFrom, 0, cpsAutoFrom, 0); // Start
Conn.Points.Add(cpsFixed, 200, cpsFixed, 100); // Middle point
Conn.Points.Add(cpsAutoTo, 0, cpsAutoTo, 0); // End
end;
Curved Connection
var
Conn: TTreeConnection;
begin
Conn := Node1.AddConnection(Node2);
Conn.Style := csCurve;
Conn.Border.Color := clGreen;
Conn.Border.Width := 3;
Conn.Border.SmallDots := False;
end;
Connection with Sides Style
var
Conn: TTreeConnection;
begin
Conn := Node1.AddConnection(Node2);
Conn.Style := csSides;
Conn.Border.Color := clMaroon;
Conn.ArrowTo.Style := casSolid;
end;
Handling Connection Click
procedure TForm1.Tree1ClickConnection(Sender: TTreeConnection;
Button: TMouseButton; Shift: TShiftState; X, Y: Integer);
begin
if Button = mbLeft then
begin
Tree1.SelectConnection(Sender);
ShowMessage('Connection from ' + Sender.FromShape.SimpleText +
' to ' + Sender.ToShape.SimpleText);
end;
end;
Programmatic Point Manipulation
var
Conn: TTreeConnection;
i: Integer;
begin
Conn := Node1.AddConnection(Node2);
Conn.Style := csLine;
// Clear auto points
Conn.Points.Clear;
// Add custom path
Conn.Points.Add(cpsAutoFrom, 0, cpsAutoFrom, 0);
// Add intermediate points
for i := 1 to 5 do
begin
Conn.Points.AddFromPrevious(50, 20 * i);
end;
Conn.Points.Add(cpsAutoTo, 0, cpsAutoTo, 0);
end;
Conditional Arrow Display
var
Conn: TTreeConnection;
begin
Conn := Node1.AddConnection(Node2);
// Show arrows based on node type
if Node1.Tag = 1 then // Start node
begin
Conn.ArrowFrom.Style := casNone;
Conn.ArrowTo.Style := casSolid;
end
else if Node1.Tag = 2 then // Bidirectional
begin
Conn.ArrowFrom.Style := casSolid;
Conn.ArrowTo.Style := casSolid;
end;
end;
Dynamic Connection Styling
var
Conn: TTreeConnection;
Distance: Double;
begin
Conn := Node1.AddConnection(Node2);
// Calculate distance
Distance := Sqrt(Sqr(Node2.Left - Node1.Left) +
Sqr(Node2.Top - Node1.Top));
// Style based on distance
if Distance < 100 then
begin
Conn.Border.Color := clGreen;
Conn.Style := csLine;
end
else if Distance < 200 then
begin
Conn.Border.Color := clYellow;
Conn.Style := csSides;
end
else
begin
Conn.Border.Color := clRed;
Conn.Style := csCurve;
end;
end;
See Also
