Nevron Open Vision Documentation
Shapes

This topic contains the following sections:
About Shapes

Shapes are the primary diagram building blocks. Shapes are used to represent objects from the real world, concepts or abstractions. In NOV diagram shapes are designed to be similar to Microsoft Visio shapes. That is why any knowledge on the Microsoft Visio shape sheet architecture will be of help to understand them. Reversely knowing about NOV Shapes can help you learn Visio internals more quickly.

Usually a shape is created by using a shape factory and then it should be added to the Items collection of a drawing page. The following code snippet demonstrates how to create a rectangle shape and add it to the to the active page of a drawing:

Creating Shapes
Copy Code
// Create a rectange
NBasicShapesFactory factory = new NBasicShapesFactory();
NShape shape = factory.CreateShape(ENBasicShapes.Rectangle);

// Position the rectangle and add it to the active page
shape.SetBounds(new NRectangle(50, 50, 100, 100));
drawing.ActivePage.Items.Add(shape);
Shape Type and Transform

The shape type is determined by the ShapeType property, which indicates whether the shape is 1D or 2D shape. The shape type influences the way in which NOV diagram threats the shape. Specifically when selected, NOV diagram will display a box tracker that allows the modification of the shape width, height, pin point and rotation. 1D shapes are visually edited by their begin and end points.

To be a fully functional 1D or 2D shape, the shape needs to be first initialized. This is done via the helper Init2DShape() and Init1DShape() methods, which initialize the shape transformation and Width and Height (in Visio also known as the shape XForm). The shape transformation is controlled by the following properties of the shape:

  • Local Pin Point

The local pin point is a point in the shape coordinate system which defines the point from the shape that is mapped to the shape location in parent coordinates – the pin point.

LocPinX, LocPinY – specify the X and Y location of the local pin point. The local pin point is in either shape “local” or “local relative” coordinates as indicated by the LocPinRelative property. The GetLocPinPoint and SetLocPinPoint methods help you get and set the local pin point in shape “local” coordinates (i.e. perform the relative to local scaling for you if needed).
LocPinRelative – indicates whether the local pin point is in shape “local” or “local relative coordinates”.

Typically the LocPinX and LocPinY are set to 0.5 and the LocPinRelative property is set to true. This is equivalent to binding the local pin point to the center of the shape Width/Height box.

  • Pin Point

The pin point is a point in shape parent coordinates, that defines the position of the shape. When the shape local pin point is projected with the shape transform, it is projected in the pin point.
That is why the modification of the pin point is associated with the shape translation. The Pin point is specified by the PinX and PinY properties. The GetPinPoint and SetPinPoint methods help you modify the pin point (both methods work in parent coordinates). If the shape belongs to a composite shape, the SetPinPoint method binds the PinX and PinY properties to a point relative to the owner composite shape Width and Height. In this way when the owner shape is resized, the shape will preserve its relative position.

  • Flipping and Rotation

The FlipX and FlipY properties define whether the shape local coordinates need to be X or Y flipped. The Angle property defines the rotation of the shape relative to the pin point.
The shape transformation is always orthogonal, meaning that any two perpendicular vectors from the shape local coordinates remain perpendicular when transformed to parent coordinates.
The shape transformation is also never a scaling transformation. This means that the distance between any two points in local coordinates will remain the same when these points are transformed to parent coordinates.


Now that you know about the properties that define the shape transformation lets discuss the actions taken by the Init2DShape() and Init1DShape() methods.

The Init2DShape() method performs the following actions:
-Sets the ShapeType to Shape2D.
-Sets the LocPinX and LocPinY properties to 0.5
-Sets the LocPinRelative to true.


The Init1DShape() takes a single argument – the type of 1D transform to initialize – there are three options – Vector, Box and BoxAbsolute. Depending on the argument the method performs the following actions:
-Sets the ShapeType to Shape1D.
-Sets the LocPinX and LocPinY properties to 0.5
-Sets the LocPinRelative to true.

Vector transform
 - binds the shape Width to be distance between the Begin and End points.
 - binds the shape Angle to be angle formed by the Begin and End line and the X axis.
 - binds the PinX and PinY properties to the middle of the line formed by the Begin and End points.

 The end result is that the shape behaves as a directed vector connecting the begin and end points. When the user moves the end-points the shape will stretch in width and rotate.


Box transform
 - binds the shape Width to be the X distance between the Begin and End points.
 - binds the shape Height to be the Y distance between the Begin and End points.
 - binds the PinX and PinY properties to the middle of the line formed by the Begin and End points.

The end result is that the shape behaves as a box defined by its left-top and right-bottom corners. When the user moves the end-points the shape will stretch in width and height. The shape will not be rotated. The shape Width and Height can become negative values with this transform. This may have the effect of X or Y flipping.


Box Absolute transform
 - binds the shape Width to be the absolute X distance between the Begin and End points.
 - binds the shape Height to be the absolute Y distance between the Begin and End points.
 - binds the PinX and PinY properties to the middle of the line formed by the Begin and End points.

The end result is that the shape behaves as a box defined by its left-top and right-bottom corners. When the user moves the end-points the shape will stretch in width and height. The shape will not be rotated. The shape Width and Height cannot become negative values with this transform so it will never look like flipped.

It is important to always initialize the shape when making a custom shape, because otherwise the shape transform properties will not be properly bound.
Shape Width and Height

The shape Width and Height properties define the size of the shape in local coordinates. Because the shape transformation is not a scaling transform, the Width and Height can also be viewed as size of the shape in the parent coordinate system.

Typically the shape geometry, ports, controls and other shape elements are created in such a way that they depends on the shape Width and Height via expressions or by using “local relative” coordinates. This however does not change the fact that the Width and Height properties do not affect the shape transformation.

For 2D shapes the Width and Height of the shape can be visually modified when the shape is selected via the box handles. For 1D shapes the Width of the shape is always expressed as a function of the Begin and End points and cannot be visually modified. The Height of the 1D shape with Vector transform however is left as a constant value and you can instruct the shape to show a height handle that will allow the visual modification of the height by setting the EditHeightIn1D property true.

Shape End Points and Glue

As discussed in the previous section, the shape transform of 1D shapes is bound to the begin and end points of the shape (collectively called end-points). The Begin and End points are points in the parent coordinate system and are controlled by the BeginX, BeginY and EndX, EndY properties of the shape.

The GetBeginPoint and SetBeginPoint methods help you modify the begin point (work in parent coordinates). Similarly the GetEndPoint and SetEndPoint methods help you modify the end point (work in parent coordinates). If the shape belongs to a group shape, the SetBeginPoint and SetEndPoint methods binds the end-point properties to a point relative to the owner group Width and Height. In this way when the owner shape is resized, the shape begin and end points will proportionally change.

Both the begin and end points can be glued to other shapes, ports and geometry aspects. The following table summarized the methods you can use the glue the begin and end points respectively:

Begin Point End Point Description

void GlueBeginToGeometryIntersection(NShape shape)

void GlueEndToGeometryIntersection(NShape shape)

Glues the respective end-point to the intersection of the 1D shape with the specified shape geometry.

void GlueBeginToGeometryContour(NShape shape, double factor)

void GlueEndToGeometryContour(NShape shape, double factor)

Glues the respective end-point to a point along the geometry contour, that corresponds to the specified factor. 0 is the begin of the geometry contour, 1 is the end of the contour.

void GlueBeginToGeometryVertex(NGeometryCommand command, int vertexIndex)

void GlueEndToGeometryVertex(NGeometryCommand command, int vertexIndex)

Glues the respective end-point to a geometry vertex of the specified geometry command.

void GlueBeginToPort(NPort fromPort)

void GlueEndToPort(NPort fromPort)

Glues the respective end-point to the specified port.

void GlueBeginToNearestPort(NShape shape)

void GlueEndToNearestPort(NShape shape)

Glues the respective end-point to the nearest port of the specified shape.

void GlueBeginToShapeBoxIntersection(NShape shape)

void GlueEndToShapeBoxIntersection(NShape shape)

Glues the respective end-point to the intersection of the 1D shape with the specified shape box.

void GlueBeginToShapeBox(NShape shape, double widthFactor, double heightFactor)

void GlueEndToShapeBox(NShape shape, double widthFactor, double heightFactor)

Glues the respective end-point to a relative point inside the specified shape box.

void GlueBeginToShapeLine(NShape shape, double factor)

void GlueEndToShapeLine(NShape shape, double factor)

Glues the respective end-point to a point along the line connecting the specified shape begin and end point points. 0 is the begin of the shape, 1 is the end of the shape.

bool GlueBeginToShape(NShape shape)

bool GlueEndToShape(NShape shape)

Glues the respective end-point to the specified shape. The actual type of connection that is performed depends on the shape DefaultShapeGlue property, which accepts values from the ENDefaultShapeGlue enumeration:

None - By default the shape does not allow shape to shape connections.

Automatic - The Begin or End point of the connectors are glued automatically depending on the shape type, geometry and ports.

In case the shape is a 2D shape:

If the shape has ports, glues to the nearest port.
Otherwise glues to the shape box intersection.

In case the shape is a 1D shape:

If the shape has ports, glues to the nearest port.
If the shape geometry has closed figures, then glues to the shape line center. 
Otherwise glues to the shape contour middle.

GlueToGeometryIntersection - The Begin or End point of the connectors are glued to the contour (outline) of the shape geometry.

GlueToBoxIntersection - The Begin or End point of the connectors are glued to the contour (outline) of the shape box.

GlueToNearestPort - The Begin or End point of the connectors are glued to the nearest port of the shape.

GlueToBoxCenter - The Begin or End point of the connectors are glued to the nearest port of the shape.    

 

Shape Elements

Each shape can have the following child elements:

Shape Events

Event Name Event Description
TransformChanged raised when the shape transformation has changed.
PageTransformChanged raised when the shape transformation to page coordinates has changed.
SizeChanged raised when the shape Width or Height has changed.
BeginPointChanged raised when the BeginX or BeginY property has changed.
EndPointChanged raised when the EndX or EndY property has changed.
GeometryChangedEvent raised when any aspect of the shape geometry has changed.
ControlsChangedEvent raised when any aspect of the shape control points has changed.
PortsChangedEvent raised when any aspect of the shape ports has changed
BeginPointGlueChangedEvent raised when any aspect of the shape begin point glue has changed
EndPointGlueChangedEvent  raised when any aspect of the shape end point glue has changed
MasterGlueChanged  raised when any aspect of the shape master glue has changed
Send Feedback