Positioning an Object in the Chart

The attach method of the AnnObj class has also been implemented to attach annotation objects to a particular point in a chart. The beauty of using the Attach method is that it accepts chart axis values instead of pixel values that the Top and Left properties require. The Attach method is an overloaded method that supports three different configurations:

AnnObj.attach(dx,dy)

AnnObj.attach(dxLeft,dyTop,dxRight,dyBottom)

AnnObj.attach(vert stringAlignment, dx, horz stringAlignment, dy)

When attaching an object using the two-parameter configuration, you are attaching the center of the annotation object to the selected point. Because you are attaching at the center, it is still required to set the height and width of the annotation object. The parameter dx represents the X axis point, and the dy represents the Y axis point you wish to attach the object.

Note: When attaching an object to a chart using the attach center method (attach(dx,dy)), it is important to understand that the center of the annotation object will be attached to the configured point. Therefore, if you attach an arrow object to a chart, the head of the arrow will not be attached to that point, rather the center point in the line of the arrow will be attached to the configured point.

When using the four-parameter configuration, the parameter dxLeft represents the left X axis value, dyTop represents the top Y axis value, dxRight represents the Right X axis value and dyBottom represents the bottom Y axis value. When attaching an object using the four-parameter configuration, each of the corners of the annotation object is attached to a particular point in the chart. Because this automatically sets the size of the object, the height and width properties are not needed unless you wish to control the object's orientation. Another benefit to using the four-parameter approach is that each of the four corners of the object is anchored to a point in the chart. This allows the object to resize when the chart itself is resized.

The attach method (Alignment overload)has been exposed which accepts a horizontal and vertical alignment setting. This allows developers to position an object (based on the black handles shown in the image) to any logical point in the plot area.

This code would attach the bottom, middle handle to the (5,20) X,Y coordinate in the chart:


' Use the 3rd Overload to Attach an Annotation text object (Attach Alignment)
annText.Attach(StringAlignment.Center,5, StringAlignment.Near,20)


// Use the 3rd Overload to Attach an Annotation text object (Attach Alignment)
annText.Attach(StringAlignment.Center,5, StringAlignment.Near,20);


' Use the 3rd Overload to Attach an Annotation text object (Attach Alignment)
annText.Attach "Center",5,"Near",20


' Use the 3rd Overload to Attach an Annotation text object (Attach Alignment)
annText.Attach "Center",5,"Near",20

The advanced anchoring feature allows developers to configure a Top, Left pixel coordinate and anchor the object to that distance from the selected margin. Therefore, if an object was anchored to the right and left of a chart while the chart was resized horizontally, the object would stretch and shrink based on the resizing.

The DrawingArea property is used to instruct how Chart FX Annotation objects will be when they overlap a chart margin. When set to true, objects will be clipped when they are positioned or scrolled over a chart margin.

Height, Width and Object Orientation

When working with annotation objects, it is very important to set the appropriate Height and Width for any object that you create. By default the height and width of each annotation object is zero (0), so by neglecting to set these properties the object will not appear in the chart.

These properties also have different effects on individual object types. For example, manipulating the height and width values for a circle object allows you to create ellipses and oval shapes. If you are creating an arrow annotation object, setting the height and width to negative values will configure the arrowhead to point in different directions. For example assigning a positive width will cause the arrow to point to the right-bottom portion of the chart. Similarly, assigning a negative value for the width will cause the arrow to point to the top-right corner of the chart. The orientation of many of the annotation objects can be altered through the use of the height and width properties including the rectangle, circle, arrow, arc and balloon objects.