Collections and Stencils

In This Topic

In the DOM, collections are usually strongly typed composites of document elements (i.e. collections can only store elements of some concrete type). The base class for all collections is the NDiagramElementCollection class (derived from NDiagramElement). It implements the INDiagramElementComposite interface, which means that you can freely insert and remove elements from a collection.

Class Hierarchy

The following image illustrates the diagram element collections class hierarchy:

Collections Summary

The following table summarizes the most important collection types:

Collection class	Description
Related to drawing documents
NLayerCollection	An instance of this collection can be obtained from the Layers property of the NDrawingDocument class. It stores the layers of a drawing.
NGuidelineCollection	An instance of this collection can be obtained from the Guidelines property of the NDrawingDocument class. It stores the drawing guidelines
NStyleSheetCollection	An instance of this collection can be obtained from the StyleSheets property of the NDrawingDocument class. It stores the stylesheets of a drawing
NArrowheadShapeStencil	An instance of this collection can be obtained from the ArrowheadShapeStencil property of the NDrawingDocument class. It is used to hold the shapes of the arrowheads, which can be displayed at the start and end point of each open figure (see below).
NPointShapeStencil	An instance of this collection can be obtained from the PointShapeStencil property of the NDrawingDocument class. It is used to hold the shapes of the points, which can be displayed by each NPointElement instances (see below).
Related to library documents
NMaster	An instance of this class is used to store reusable drawing clippings. The NLibraryDocument is in fact a collection of masters. See Library Documents for more information.
Related to shapes
NLabelCollection	An instance of this collection can be obtained from the Labels property of the NShape class. It is used to store the labels of a shape. See Labels for more information.
NPortCollection	An instance of this collection can be obtained from the Ports property of the NShape class. It is used to store the ports of a shape. See Ports for more information.
NControlPointCollection	An instance of this collection can be obtained from the ControlPoints property of the NShape class. It is used to store the control points of a shape. See Control Points for more information.
NPrimitiveModelCollection	An instance of this collection can be obtained from the Primitives property of the NCompositeShape class. It is used to store the primitives, from which a composite shape is constructed. See Composite Shapes for more information.
NShapeCollection	An instance of this collection can be obtained from the Shapes property of the NGroup class. It is used to store the shapes of a group. See Groups for more information.

Stencils

Stencils are collections, which contain and render some reusable content. Stencil collections are derived from the base NStencil class, which derives from NDiagramElementCollection.

Stencils are designed to be fast and can generally render two types of transformable content - predefined and custom. The predefined content is stencil specific. The custom content of each stencil is defined with the help of one or more strongly named NModel derivates, which the stencil contains.

Currently each NDrawingDocument hosts two more specialized stencils - NArrowheadShapeStencil and NPointShapeStencil. Following is a brief description of these stencils:

Arrowhead Shape Stencil
This type of stencil is used to store the shapes of the available arrowheads. Arrowheads are typically displayed by open figure NPathPrimitive derivates (i.e. open figure paths). Arrowheads can be displayed at the start and/or end point of an open figure path. The type of shape, which must be displayed at the start and end points is determined by the composed Start Arrowhead Style and End Arrowhead Style of the current node style. For example:

C#	Copy Code
// obtain the styles of the start and end arrowheads NArrowHeadStyle startAHStyle = path.ComposeStartArrowheadStyle(); NArrowHeadStyle endAHStyle = path.ComposeEndArrowheadStyle();

Visual Basic	Copy Code
' obtain the styles of the start and end arrowheads Dim startAHStyle As NArrowheadStyle = path.ComposeStartArrowheadStyle() Dim endAHStyle As NArrowheadStyle = path.ComposeEndArrowheadStyle()

When an arrowhead shape stencil is attached to a NPaintContext instance the paint context will call its PaintArrowheadAppearance and PaintArrowheadShadow methods, when it needs to display an arrowhead appearance or shadow.

The arrowhead shape stencil hosts two types of arrowhead shapes:

1. Predefined arrowhead shapes - the predefined arrowhead shapes are instances of the NArrowheadShape class and are enumerated by the ArrowheadShape enumeration. You can gain access to the predefined arrowhead shapes via the PredefinedArrowheadShapes property of the arrowhead shape stencil. Predefined arrowheads are faster to obtain and display. The following code instructs a line to have a predefined arrowhead:

C#	Copy Code
line.Style.StartArrowheadStyle = new NArrowheadStyle(ArrowheadShape.Circle, "", new NSizeL(12, 12), new NColorFillStyle(Color.Red), new NStrokeStyle(1, Color.Black));

Visual Basic	Copy Code
line.Style.StartArrowheadStyle = New NArrowheadStyle(ArrowheadShape.Circle, "", New NSizeL(12, 12), New NColorFillStyle(Color.Red), New NStrokeStyle(1, Color.Black))

2. Custom arrowhead shapes - the custom arrowhead shapes are contained in the stencil collection. You can insert any model in the arrowhead shape stencil. Custom arrowheads are obtained by their name so it is important to provide an unique name to your shape. In order to specify a custom arrowhead you must set the arrowhead shape to Custom and provide a valid CustomName. For example:

C#	Copy Code
// display a custom start arrowhead with the specified name and styles line.Style.StartArrowheadStyle = new NArrowheadStyle(ArrowheadShape.Custom, "MyArrowhead", new NSizeL(12, 12), new NColorFillStyle(Color.Red), new NStrokeStyle(1, Color.Black)); // register a custom arrowhead shape in the stencil (in this case a simple rectangle) NRectangleF modelBounds = new NRectangleF(0, -1, 2, 2); NRectanglePath rect = new NRectanglePath(modelBounds); rect.Name = "MyArrowhead"; document.ArrowheadShapeStencil.AddChild(rect);

Copy Code

// display a custom start arrowhead with the specified name and styles
line.Style.StartArrowheadStyle = new NArrowheadStyle(ArrowheadShape.Custom, "MyArrowhead",  new NSizeL(12, 12), new NColorFillStyle(Color.Red), new NStrokeStyle(1, Color.Black));   
// register a custom arrowhead shape in the stencil (in this case a simple rectangle)
NRectangleF modelBounds = new NRectangleF(0, -1, 2, 2);
NRectanglePath rect = new NRectanglePath(modelBounds);
rect.Name = "MyArrowhead";
document.ArrowheadShapeStencil.AddChild(rect);

Visual Basic	Copy Code
' display a custom start arrowhead with the specified name and styles line.Style.StartArrowheadStyle = New NArrowheadStyle(ArrowheadShape.Custom, "MyArrowhead", New NSizeL(12, 12), New NColorFillStyle(Color.Red), New NStrokeStyle(1, Color.Black)) ' register a custom arrowhead shape in the stencil (in this case a simple rectangle) Dim modelBounds As New NRectangleF(0, -1, 2, 2) Dim rect As New NRectanglePath(modelBounds) rect.Name = "MyArrowhead" document.ArrowheadShapeStencil.AddChild(rect)

Visual Basic

Copy Code

' display a custom start arrowhead with the specified name and styles
line.Style.StartArrowheadStyle = New NArrowheadStyle(ArrowheadShape.Custom, "MyArrowhead", New NSizeL(12, 12), New NColorFillStyle(Color.Red), New NStrokeStyle(1, Color.Black))

' register a custom arrowhead shape in the stencil (in this case a simple rectangle)
Dim modelBounds As New NRectangleF(0, -1, 2, 2)
Dim rect As New NRectanglePath(modelBounds)
rect.Name = "MyArrowhead"
document.ArrowheadShapeStencil.AddChild(rect)

It is important to know that the point around which the arrowhead is rotated is the (0, 0) point of the arrowhead shape. The following image illustrates the predefined arrowhead shapes:

Point Shape Stencil
This stencil is used to store the shapes of the available points. Points are scale independent objects, which means that they are always displayed and measured in device coordinates (pixels). The point shapes are displayed by instances of the NPointElement class.

The point shape stencil is very similar to the arrowhead shape stencil. It again exposes an array of predefined points through its PredefinedPointShapes property, containing NPointShape instances. The predefined points are enumerated by the PointShape enumeration. You can also add custom shapes in this stencil.

The following image illustrates the predefined point shapes:

Related Examples

Windows Forms: Document Object Model - Stencils Folder