AnnotationXY

Annotations allow displaying mouse-interactive text labels or graphics anywhere in the chart area. Annotations can be moved around by mouse, resized, rotated, their target and location can be changed etc. Alternatively, they can be controlled by code. Annotations are great also when custom graphics must be rendered on the screen, as they can be rendered in different styles and shapes. Create AnnotationXY objects in ViewXY.Annotations collection.

By moving mouse over an annotation, it goes into mouse-interactive edit state, allowing relocation, resizing it, rotating it, and determining where the arrow points to.

Move mouse over the annotation to enter the editing state. Move mouse away to leave the edit state.

AnnotationXY objects with various styles, placed around a line series. Use Style property to select the shape.

Controlling target and location

Target is the ending point of the arrow, the point that the arrow or callout tip points to. Target can be set in axis values or in screen coordinates. Use TargetCoordinateSystem to select between AxisValues or ScreenCoordinates. When AxisValues is selected, TargetAxisValues property sets where the arrow line points to (end of the arrow line). Use TargetScreenCoords property to set it in screen coordinates instead.

Location is the starting point of the arrow. It can be set by screen coordinates, axis values, or as relative offset from Target. Use LocationCoordinateSystem to select, and LocationScreenCoords, LocationAxisValues or LocationRelativeOffset to control the location by the selected method. Location is also the center point of text area rotation.

Anchor property controls how the text area is placed at Location. By setting Anchor.X = 0.5 and Anchor.Y = 0.5, the beginning of the arrow is in the middle of text-box. When setting Anchor.X 0.1 and Anchor.Y = 0.25, arrow start is near the upper left corner as the following figure illustrates:

Anchor values explained. Current Anchor.X = 0.1 and Anchor.Y = 0.25. When the anchor values are between 0…1, the arrow start point is inside the text area.

Using mouse to move, rotate and resize

Annotation mouse-interactive nodes

Drag from Target to move the end of the arrow. Drag from text area to set new Location. By dragging from round location/anchor node, Anchor and Location properties can be adjusted at the same time, keeping the text box in the same place.

By holding Shift key down while dragging from X or Y resize node, a symmetrical operation is used, both sides are adjusted at same time. By holding Shift key down while dragging from a corner resize node (X+Y), resizing maintains the aspect ratio. In rotate operation, Shift key snaps the rotate angle to nearest multiple of 15 degrees.

Adjusting appearance

Select the annotation shape by setting Style property. The options are: Rectangle, RectangleArrow, RoundedRectangle, RoundedRectangleArrow, Arrow, Callout, RoundedCallout, Ellipse, EllipseArrow, Triangle and TriangleArrow.

For styles with arrow, use ArrowLineStyle, ArrowStyleBegin and ArrowStyleEnd to control the arrow design. As arrow end styles, there are options: None, Square, Arrow, Circle and Caliper.

Use Fill to modify the fill of the annotation. Note, if annotation fill is not visible (Fill. Style = None) or color are semitransparent, then Shadow. Color will be visible. To hide shadow disable Shadow. Visible property.

The appearance of the editing state mouse-interactive nodes can be changed from NibStyle. TextStyle controls the font settings and text alignment inside the text area. BorderLineStyle and CornerRoundRadius control the border line appearance (if BorderVisible is enabled).

Arrow style appearance

Arrowhead is drawn, when Style property is set to an option with arrow, and ArrowStyleEnd or ArrowStyleBegin style set as Arrow, Circle and Caliper. Default arrowhead is created from equilateral triangle, where side length is 3 time of line-width (ArrowLineStyle. Width).

Default arrow style for Annotation (equilateral triangle).

From version 12.4 Annotation's arrow has more properties for adjustment. In particular, ArrowEndWidthMultiplicator and ArrowBeginWidthMultiplicator has been added (default is 1). Those properties allow more fine control of arrow width. That is, width can be any multiple of line-width (ArrowLineStyle. Width).

Annotation arrow style with ArrowEndWidthMultiplicator = 3, ArrowEndAspectRatio = 1.

It is also possible to draw arrowhead using other shapes besides equilateral triangle. ArrowEndAspectRatio property controls arrow end aspect ratio (width / height), where default is 1.

Annotation arrow style with ArrowEndWidthMultiplicator = 2, ArrowEndAspectRatio = 2.

Size settings

Sizing property controls how the annotation text box is sized:

• Automatic adjusts the size by the contents, and leaves AutoSizePadding space to the borders.
• AxisValuesBoundaries allows the size of the annotation to be set in axis values. Use AxisValuesBoundaries. XMin, XMax, YMin and YMax to define them.
• ScreenCoordinates enables setting size in the screen coordinates. Use SizeScreenCoords. Height and Width.

From version 12.4 new property is added to Annotation base class (therefore, applicable for Annotations in all Views). Annotation. Size is read only property, which gets the size of annotation text bounding box (after chart is rendered). Size has Width and Height fields. This property is handy, when user needs to know the final/current size of the Annotation (for example, after resizing or text change).

Keeping text area visible

When KeepVisible is enabled, the annotation text area is forced inside the graph. The annotation won't move outside the graph when moving it by mouse or code. When panning the graph view or adjusting axes, the annotations are repositioned to show inside the graph.

Clipping inside graph

When ClipInsideGraph is enabled, the annotation is clipped inside the graph. When it’s disabled, the annotation is rendered also in the margin area of the chart.

By enabling ClipWhenSweeping, the annotation doesn’t show up in the sweeping gap area when ScrollMode is set Sweeping.

Displaying annotation over axes

By setting RenderBehindAxes = True, annotation is shown under axes. All clipping and Z ordering features are not feasible in that case. RenderBehindAxis has no effect if ClipInsideGraph is set true.

On the left RenderBehindAxes = True, on the right RenderBehindAxes = False. ClipInsideGraph is set False in both cases.

Controlling the Z order

By setting Behind property to its default value, False, the annotation appears on top of series. By setting it True, it is rendered before the series, thus appearing under them.

The annotations appear in the order they exist in Annotations list, while keeping the Behind filter as a master controller. Annotations Z order can be changed quickly by using ChangeOrder method of annotation for example in a mouse event handler. The options for order change are:

• BringToFront brings the annotation to topmost
• SendToBack sends to back
• MoveBack moves one step backwards
• MoveFront moves one step forwards

tip

A use case of annotation.ChangeOrder() method can be found in ExampleAnnotationsXY from our Demo.

LayerGrouping performance optimization

When having hundreds of annotations with visible text, the delay of text rendering starts to play a significant role. By default, text rendering follows the Z order, keeping the text firmly within an annotation.

The performance can be improved by setting LayerGrouping = True, and the chart will use only two flat annotation text layers. One for annotations with Behind set to True, and other for annotations with Behind set to False. It greatly improves performance. On the other hand, the text will be rendered wrong if there are overlap between annotations.

On the left LayerGrouping = False. On the right, LayerGrouping = True, Z order of texts is lost.

When using Style = Arrow or by setting the annotation fill not visible (Fill. Style = None), the restriction of Z order typically doesn't show up.

Converting between axis values and screen coordinates

In some cases, Location or Target may be wanted to be defined in mixed configuration. First in screen coordinates and second in axis values, or vice versa. Axes have ValueToCoord method for converting an axis value to a screen coordinate, and CoordToValue to convert a screen coordinate to an axis value as described in Axis properties.