Ports

In This Topic

Ports are connection points to which multiple plugs can be attached. Ports themselves can be anchored to specific aspects of the shape to which they belong, or to any of the models the shape aggregates. The ports of a shape are contained in an instance of the NPortCollection class, which can be obtained from the Ports property of the shape. Ports are one of the optional shape elements and may not be available by default for each shape (see Shapes for more information).

All types of ports derive from the base NPort class. Ports use the following class hierarchy:

All types of ports share the following set of features:

Anchor Model

The port location is implicitly defined by the model to which the port is anchored. Different types of ports use different metrics of the anchor model, but all types of ports need an anchor model.

The model to which the port is anchored is specified by the AnchorUniqueId property. In case this property is equal to Guid.Empty the port is by default considered anchored to the shape to which it belongs. You can obtain a reference to the anchor model with the help of the GetAnchorModel method.

Since both shapes and primitives are models (derived from the base NModel class), this gives you the ability to author complex shapes the ports of which can be anchored to very specific aspects of the shape.

Offset

The base port location is defined by an anchor model and an additional port specific metric. For example the NPointPort defines a base port location which is the location of a model geometry point.

The actual port location is the base port location plus the constant offset specified by the Offset property. The offset is always specified in scene units.

Port Type

Each port has the option to choose its type in regards to what and how can be connected to it. This is specified by the Type property, which accepts a value from the PortType enumeration:

Inward - this is the default port type. Plugs and outward ports can be connected to inward ports. For an inward port you can obtain the plus and outward ports which are currently connected to it via the Plugs and OutwardPorts properties respectively. You can also disconnect all currently connected plugs and outward ports with the help of the DisconnectPlugs() and DisconnectOutwardPorts() methods respectively.

Inward ports are displayed with the sign (X sign).
Outward - this type of port does not allow plugs to be connected to it. An outward port however can be connected to an inward port via the Connect method of the port. When connected, the outward port controls the location and orientation of the shape to which it belongs. It will automatically rotate and translate the shape according to the following two rules:

1. The shape is translated so that the outward port location becomes the current inward port location

2. The shape is rotated so that the outward port direction matches the inward port direction.

Outward ports are displayed with the sign (dot sign).
InwardAndOutward - this is a mixture of the above mentioned modes. Inward and outward ports are displayed with the sign (star sign).

Direction

The port direction plays a significant role in an inward - outward port connection. The current point direction is obtained by the GetDirection method and is measured in radians relative to the scene coordinate system.

In general the port direction is automatically determined by the DirectionMode property, which is specific for each type of port. All direction modes however support a custom direction mode setting, in the case of which the direction is controlled by the CustomDirectionAngle property.

Currently Available Ports

The following table summarizes the currently available types of ports and their anchoring options and direction modes:

Port class	Anchor Options	Direction Modes
NPointPort	Can be anchored to a specific point of the shape or the models it aggregates. You have the option to specify either a custom point index or a predefined one: first, second, last, last but one and middle.	Can automatically determine a direction, which is formed by the line connecting the port location the prev point, next point or anchor model center.
NLogicalLinePort	Can be anchored to the percent position of the logical line of the shape or the models it aggregates.	Can automatically determine a direction, which is orthogonal to the anchor model logical line percent direction.
NBoundsPort	Can be anchored to the scene bounds of the shape or the models it aggregates. You can specify an alignment relative to the bounds.	Can automatically determine a direction, which is formed by the port location and the anchor model center, or is orthogonal the nearest side of the anchor model rotated bounds.
NRotatedBoundsPort	Can be anchored to the rotated bounds of the shape or the models it aggregates. You can specify an alignment relative to the rotated bounds.	Can automatically determine a direction, which is formed by the port location and the anchor model center, or is orthogonal the nearest side of the anchor model model bounds.
NDynamicPort	Can be anchored to the rotated bounds of the shape or the models it aggregates. You can specify an alignment relative to the rotated bounds. Unlike the other types of ports, which glue to plugs to their position (e.g. static glue), the dynamic port can glue the plugs to different positions (e.g. dynamic glue - dynamically calculate an appropriate glue position for each connected plug). The positions to which a dynamic port glues the plugs connected to it is controlled by it's GlueMode property (accepts values from the DynamicPortGlueMode enumeration).	Can automatically determine a direction, which is formed by the port location and the anchor model center, or is orthogonal the nearest side of the anchor model rotated bounds.

Default Ports and Implicit Connections

Of all ports, which can reside in the ports collection of a shape one is considered as the default inward port (primary inward port) and one is considered as the default outward port (primary outward port).

The default inward port is specified by the DefaultInwardPortUniqueId property of the NPortCollection class and can be obtained from the DefaultInwardPort property.

Similarly the default outward port is specified by the DefaultOutwardPortUniqueId property of the NPortCollection class and can be obtained from the DefaultOutwardPort property.

The following example adds a port to a shape and makes it the default inward port:

C#	Copy Code
// create the shape ports, if not already created if (shape.Ports == null) { shape.CreateShapeElements(ShapeElementsMask.Ports); } // create a dynamic port anchored to the shape NDynamicPort port = new NDynamicPort(shape.UniqueId, ContentAlignment.MiddleCenter, DynamicPortGlueMode.GlueToContour); shape.Ports.AddChild(port); shape.Ports.DefaultInwardPortUniqueId = port.UniqueId;

Copy Code

// create the shape ports, if not already created
if (shape.Ports == null)
{
    shape.CreateShapeElements(ShapeElementsMask.Ports);
}

// create a dynamic port anchored to the shape
NDynamicPort port = new NDynamicPort(shape.UniqueId, ContentAlignment.MiddleCenter, DynamicPortGlueMode.GlueToContour);
shape.Ports.AddChild(port);
shape.Ports.DefaultInwardPortUniqueId = port.UniqueId;

Visual Basic	Copy Code
' create the shape ports, if not already created If shape.Ports Is Nothing Then shape.CreateShapeElements(ShapeElementsMask.Ports) End If ' create a dynamic port anchored to the shape Dim port As New NDynamicPort(shape.UniqueId, ContentAlignment.MiddleCenter, DynamicPortGlueMode.GlueToContour) shape.Ports.AddChild(port) shape.Ports.DefaultInwardPortUniqueId = port.UniqueId

Visual Basic

Copy Code

' create the shape ports, if not already created
If shape.Ports Is Nothing Then
    shape.CreateShapeElements(ShapeElementsMask.Ports)
End If

' create a dynamic port anchored to the shape
Dim port As New NDynamicPort(shape.UniqueId, ContentAlignment.MiddleCenter, DynamicPortGlueMode.GlueToContour)
shape.Ports.AddChild(port)
shape.Ports.DefaultInwardPortUniqueId = port.UniqueId

The default inward port is the port to which plugs and outward ports connect in implicit connections (shape to shape connections). For example:

When you set the FromShape/ToShape property of a 1D shape you are actually connecting the start/end plug of that shape to the default inward port of the specified shape.

Similarly when you set the InwardShape property of a shape you are actually connecting the default outward port of that shape to the default inward port of the specified shape.

Advanced Considerations

Although the inward/outward port connection concept is simple, there are two rules for which you need to be aware when creating inward/outward port connections:

1. Of all outward ports of a shape only one can be connected at a time. The rule is automatically enforced when you connect an outward port. The rule is needed, because if two outward ports are connected at the same time the translation/rotation becomes ambiguous.

2. Either an outward port or plugs can be connected at a time. The rule is applicable only for 1D shapes with an outward port. The rule is automatically enforced when you connect an outward port or a plug. The rule is needed because if an outward port is connected at the same time when a plug is connected the translation/rotation and plugs glue became ambiguous.

Related Examples

Windows Forms: Document Object Model - Shapes - Shape Ports

Windows Forms: Document Object Model - Shapes - Shape Outward Ports