ProEssentials provide for a wide variety of annotations. These fall into four categories, graph annotations, line annotations, axis annotations, and version 5 added table annotations..

• Table Annotations are annotations that create a table of information that can be placed within and around the graphing region. They allow for symbols and text to be grouped together with hot-spot, header rows and columns, real-time update, and more. Table annotations can be used with any of the ProEssentials controls.

• Graph Annotations are annotations within the graphing region. They allow for drawing points, line segments, placing text, rectangles, polygons, and more.

• Line Annotations provide a simple interface to add vertical and horizontal lines to a chart. Line Annotations have the ability to place their text outside the graphing area in a variety of justifications. They can also process a carriage-return to allow for two lines of text. They also are one mechanism to construct custom axis scales where the developer chooses where grid line and tick marks are placed, and what text gets associated with grid lines.

• Axis Annotations are annotations that line the inside of the graph and mark a location on the axis. They have the unique ability to fan out to prevent adjacent annotations from overlapping each other's text.

In order for annotations to be visible, ShowAnnotations must be TRUE. Also, if AllowAnnotationControl is TRUE, the user will have the capability to toggle the annotations on/off via the customization dialog or popup menu. Table annotations have their own property to control visiblility which is ShowTableAnnotation.

The Graph and Scientific Graph objects both have full and identical annotation capabilities. Since the Graph object does not contain XData, x axis location is defined by the data-point number. For example, an x axis location of 1.5 is half way between the first and second data-points.

The Polar/Smith object is only compatible with the graph annotation mechanism and does not support line or axis annotations.

The 3D Scientific Graph supports graph annotations, however, they are only shown during wireframe images or 3D Scatter mode charts. AnnotationsOnSurfaces can be used to disable this limitation. Line Annotations create extra grid lines on the 3D axes. Unique to the 3D Scientific Graph is ZAxisLineAnnotation which places line annotations on the z axis. VertLineAnnotation places lines along X axis and HorzLineAnnotation places lines along Y axis. Axis annotations are not supported.

The Pie Chart object does not support annotations except for Table Annotations.

Table Annotations

  Table annotations are implemented with the following properties.

The following code adds a simple table annotation to a chart...

VB6 Code, NET and Delphi code is similar:

The above code creates the following table annotation results...

Refer to the example code, examples 026, 027, 028, 029, and 030 for more information.

Graph Annotations

Text strings, symbols, symbols+text, rects, ellipses, complex lines and shapes can be added via the property arrays...

Graph annotation text size is controlled globally by GraphAnnotationTextSize.

GraphAnnotationAxis is only used in combination with MultiAxesSubsets. It should be ignored if MultiAxesSubsets is not being set.

This group of property arrays comprises the graph annotation mechanism. Each defines a different aspect of the annotation, for example, its x location, y location, type, text, color, and axis. The type is defined by a PEGAT_ constant described in the reference material under GraphAnnotationType. Annotations are bound by sharing the same index. For example, all the properties below share the same index (0), thus all describe different attributes of the first graph annotation.

Non-orthogonal and complex line drawing can be accomplished with a MoveTo/LineTo style mechanism. The following example adds a triangle to the graph:

Various styled Ellipses, Rectangles, and Round-Rectangles can also be added via the graph annotation mechanism. These types of annotations take three graph annotations to describe. One annotation defines the top-left, the second defines the bottom-right, and the third defines the annotation type and the location of any text belonging to the rect/ellipse. The following example adds an ellipse:

It's important that when drawing rectangles and ellipses, that the third annotation PEGAT_RECT_ xx or PEGAT_ELLIPSE_ xx defines a GraphAnnotationX and GraphAnnotationY within the charting region. It's a common practice to duplicate the x and y coordinates of the PEGAT_BOTTOMRIGHT annotation. This is demonstrated in the above example. The x and y coordinates will define the location of GraphAnnotationText if provided.

The following is the output produced by the above annotation example code. It shows the two points with text, the triangle line drawing, and the ellipse.  The demo example 015 also shows graph annotations.

Line Annotations

Horizontal lines can be added with the following properties:

Vertical lines can be added with the following properties:

Line annotation text size is controlled by LineAnnotationTextSize.

HorzLineAnnotationAxis is only used in combination with MultiAxesSubsets. It should be ignored if MultiAxesSubsets is not being set.

As with graph annotations, each of the above defines a different aspect of the annotation, for example, its location, type, text, color, and axis. The type is defined by a PELT_ constant described in the reference material under HorzLineAnnotationType. Annotations are bound by sharing the same index. For example, all the properties below share the same index (0), thus all describe different attributes of the first horizontal line annotation.

Line annotations also support placing their text outside the graphing area. The above text "|RRightText" is preceded with the justification code |R (pipe symbol + R). This positions the text to the far-right outside-edge of the graph. Refer to Appendix B, and HorzLineAnnotationText for more information on justifying annotation text.

Anytime you use a justification code that places text outside the graphing area, you need to allocate space for the text with the LeftMargin, RightMargin, TopMargin, or BottomMargin properties. ShowMargins can further control existence of margins.

Since the above code uses the |R justification code, we need to allocate space with the RightMargin property. Margin type properties are textual but ProEssentials only uses the text to calculate the required space to allocate.

The following image shows the results of placing the above horizontal line annotation.

If you need to produce a line annotation without the line, and only the text, use a line annotation type of negative 1 (-1). This will draw a line with a Null Pen and only place the text you define.

If you need to plot a line or graph annotation with respect to units on the right y axis, add 1000 to the annotation type. You will do this only if using RYAxisComparisonSubsets.

The demo's example 101 shows line annotations.

Axis Annotations

X axis and y axis annotations consist of text strings attached to a location on the axis. The finest feature about axis annotations is that they have logic to prevent adjacent annotations from overlapping. This is useful when you want to place a large number of annotations along an axis. Because these annotations are within the graph, if your axis annotation text will be long, you will generally want to manually scale the axes to assure axis annotation text does not conflict with your plotted data.

Axis annotations consist of:

Axis annotation text size is controlled by AxesAnnotationTextSize.

Y axis annotations are currently not compatible with the use of MultiAxesSubsets.

Like graph and line annotations, each of the above defines a different aspect of the annotation, for example, its location, text, and color.

Below is some code which creates 4 axis annotations. Note that XAxisAnnotationColor is optional.

The following image shows the axis annotations produced by the above code.