Visit Gigasoft's Web Site
ProEssentials v8 Help

Chapter 6: Annotations Explained

 

ProEssentials provide for a wide variety of annotations. These fall into four categories, graph annotations, line annotations, axis annotations, and 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.

 

WorkingTable

Working Table, controls which set of table parameters are set/get. Values range from 0-19

TARows

Number of rows in table

TAColumns

Number of columns in table

TAType

Type of cell

TAText

Text for cell

TAColor

Foreground Color of cell.

TAHotSpot

Non-Zero to designate cell as a hot spot

TAHeaderRows

Number of header rows

TAHeaderColumn

TRUE if first column is column heading

TAColumnWidth

Units in characters, sets default widths of columns

TAHeaderOrientation

0 = horizontal, 1 = 90 degrees, 2 = 270 degrees

TaBorder

Border Type, 0=shadow, 1=line, 2=no border, 3=inset effect

TABackColor

Table's bacground color, setting to 1  equals DeskColor or GraphBackColor based on location

TAForeColor

Assigns a table fore color or 1 to use TextColor

TATextSize

Sets relative size, for example  85 to 120 or as needed

ShowTableAnnotation

TRUE to include this table in image

TAJustification

Control justifications on per cell basis

TAFont

Global font property for entire table

TAFonts

Font control on per cell basis

TALocation

Controls locations of table

TAAxisLocation

Provides additional location settings when TALocation sets table within an multiaxis region

 

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

Pego1.PeAnnotation.Table.Rows = 4;
Pego1.PeAnnotation.Table.Columns = 7;

// Pass the table text //
Pego1.PeAnnotation.Table.Text[1, 0] = " 1 "; // left column, column index 0
Pego1.PeAnnotation.Table.Text[2, 0] = " 2 ";
Pego1.PeAnnotation.Table.Text[3, 0] = " 3 ";

Pego1.PeAnnotation.Table.Text[0, 1] = "Try not "; // top row, row index 0
Pego1.PeAnnotation.Table.Text[0, 2] = "... ";
Pego1.PeAnnotation.Table.Text[0, 3] = "Do ";
Pego1.PeAnnotation.Table.Text[0, 4] = "... ";
Pego1.PeAnnotation.Table.Text[0, 5] = "or ";
Pego1.PeAnnotation.Table.Text[0, 6] = "Do not ";

Int32 r, c;
for(r=1; r<4; r++)
{
    for(c=1; c<7; c++)
    {
        Pego1.PeAnnotation.Table.Text[r, c] = String.Format( "{0:###0.000}",
            (System.Math.Sin(0.3 * c + 1) * 500.0) + ((float)(Rand_Num.NextDouble()) * 50));
        Pego1.PeAnnotation.Table.Color[r, c] = Color.FromArgb(255, 0, 0, 0);
    }
}

// Other Table Related Properties ///
Pego1.PeAnnotation.Table.Show = true;
Pego1.PeAnnotation.Table.Location = GraphTALocation.InsideTopLeft;
Pego1.PeAnnotation.Table.BackColor = Color.FromArgb(5, 150, 150, 150);
Pego1.PeAnnotation.Table.GradientStyle = PlotGradientStyle.VerticalAscent;
Pego1.PeAnnotation.Table.GradientColor = Color.White;
Pego1.PeAnnotation.Table.BevelStyle = BevelStyle.ThinSmooth;
Pego1.PeAnnotation.Table.Border = TABorder.NoBorder; Pego1.PeAnnotation.Table.HeaderRows = 1;
Pego1.PeAnnotation.Table.HeaderColumn = true;

 

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...

 

GraphAnnotationX

X location of annotation.

GraphAnnotationY

Y location of annotation.

GraphAnnotationType

Annotation type.

GraphAnnotationText

Text associated with this annotation. Can include various justification codes.

GraphAnnotationColor

Color of annotation.

GraphAnnotationAxis

Axis location (0 - 5) if using Multi-Axes.

GraphAnnotationHotSpot

Non-Zero to designate annotation as a hot spot.

GraphAnnotMoveable

Used with Pointer type graph annotations. Allows user to adjust location of associated text.

 

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. Annotations are bound by sharing the same index. For example, all the properties below sharing the same index (0) relate to the symbol "Dot Gradient Shadow".

 

// simplify chart by reducing subsets //
Pego1.PeData.Subsets = 2;
Pego1.PePlot.Method = GraphPlottingMethod.PointsPlusLine;
Pego1.PePlot.RYAxisComparisonSubsets = 1;
Pego1.PePlot.MethodII = GraphPlottingMethodII.Line;
Pego1.PeTable.Show = GraphPlusTable.Graph;
Pego1.PeFont.FontSize = FontSize.Large;

// Add some various graph annotations //
Pego1.PeAnnotation.Show = true;
Pego1.PeFont.GraphAnnotationTextSize = 115;

// Controls default placement of all annotations //
Pego1.PeAnnotation.InFront = false;

// Give user ability to show or hide annotations //
Pego1.PeUserInterface.Menu.AnnotationControl = true;

// Place a symbol //
Pego1.PeAnnotation.Graph.X[0] = 1.5;
Pego1.PeAnnotation.Graph.Y[0] = 1095;
Pego1.PeAnnotation.Graph.Type[0] = (int) GraphAnnotationType.SmallDotSolid;
Pego1.PeAnnotation.Graph.Color[0] = Color.FromArgb(225, 198, 98, 0);
Pego1.PeAnnotation.Graph.Text[0] = "Dot Gradient Shadow";
Pego1.PeAnnotation.Graph.GradientStyle[0] = (int) PlotGradientStyle.RadialTopLeft;
Pego1.PeAnnotation.Graph.Shadow[0] = true;
Pego1.PeAnnotation.Graph.Bold[0] = false;

// Draw some lines //
Pego1.PeAnnotation.Graph.X[1] = 1.5;
Pego1.PeAnnotation.Graph.Y[1] = 1020;
Pego1.PeAnnotation.Graph.Type[1] = (int) GraphAnnotationType.ThinSolidLine;
Pego1.PeAnnotation.Graph.Color[1] = Color.FromArgb(0, 198, 198);
Pego1.PeAnnotation.Graph.Text[1] = "Start";
Pego1.PeAnnotation.Graph.Bold[1] = false;

Pego1.PeAnnotation.Graph.X[2] = 2.5;
Pego1.PeAnnotation.Graph.Y[2] = 1120;
Pego1.PeAnnotation.Graph.Type[2] = (int) GraphAnnotationType.LineContinue;
Pego1.PeAnnotation.Graph.Color[2] = Color.Black;
Pego1.PeAnnotation.Graph.Text[2] = "";

Pego1.PeAnnotation.Graph.X[3] = 3.5;
Pego1.PeAnnotation.Graph.Y[3] = 1020;
Pego1.PeAnnotation.Graph.Type[3] = (int) GraphAnnotationType.LineContinue;
Pego1.PeAnnotation.Graph.Color[3] = Color.FromArgb(0, 0, 198);
Pego1.PeAnnotation.Graph.Text[3] = "End";
Pego1.PeAnnotation.Graph.Bold[3] = false;

// How to draw an ellipse, rectangle, or roundrect. //
Pego1.PeAnnotation.Graph.X[4] = 4.5;
Pego1.PeAnnotation.Graph.Y[4] = 1120;
Pego1.PeAnnotation.Graph.Type[4] = (int) GraphAnnotationType.TopLeft;
Pego1.PeAnnotation.Graph.Color[4] = Color.Black;
Pego1.PeAnnotation.Graph.Text[4] = "";
Pego1.PeAnnotation.Graph.InFront[4] = AnnotationInFront.InFront;
Pego1.PeAnnotation.Graph.Shadow[4] = true;

Pego1.PeAnnotation.Graph.X[5] = 5.5;
Pego1.PeAnnotation.Graph.Y[5] = 1020;
Pego1.PeAnnotation.Graph.Type[5] = (int) GraphAnnotationType.BottomRight;
Pego1.PeAnnotation.Graph.Color[5] = Color.Black;
Pego1.PeAnnotation.Graph.Text[5] = "";
Pego1.PeAnnotation.Graph.InFront[5] = AnnotationInFront.InFront;
Pego1.PeAnnotation.Graph.Shadow[5] = true;

Pego1.PeAnnotation.Graph.X[6] = 5.5;
Pego1.PeAnnotation.Graph.Y[6] = 1020;
Pego1.PeAnnotation.Graph.Type[6] = (int) GraphAnnotationType.EllipseFill;
Pego1.PeAnnotation.Graph.Color[6] = Color.FromArgb(155, 234, 123, 53);
Pego1.PeAnnotation.Graph.Text[6] = "";
Pego1.PeAnnotation.Graph.InFront[6] = AnnotationInFront.InFront;
Pego1.PeAnnotation.Graph.Shadow[6] = true;
Pego1.PeAnnotation.Graph.GradientStyle[6] = (int) PlotGradientStyle.RadialTopLeft;

// Place a polygon //
Pego1.PeAnnotation.Graph.X[7] = 6.5;
Pego1.PeAnnotation.Graph.Y[7] = 1120;
Pego1.PeAnnotation.Graph.Type[7] = (int) GraphAnnotationType.StartPoly;
Pego1.PeAnnotation.Graph.Color[7] = Color.Black;
Pego1.PeAnnotation.Graph.Text[7] = "";

Pego1.PeAnnotation.Graph.X[8] = 7.5;
Pego1.PeAnnotation.Graph.Y[8] = 1120;
Pego1.PeAnnotation.Graph.Type[8] = (int) GraphAnnotationType.AddPolyPoint;
Pego1.PeAnnotation.Graph.Color[8] = Color.Black;
Pego1.PeAnnotation.Graph.Text[8] = "";

Pego1.PeAnnotation.Graph.X[9] = 7.5;
Pego1.PeAnnotation.Graph.Y[9] = 1020;
Pego1.PeAnnotation.Graph.Type[9] = (int) GraphAnnotationType.EndPolygon;
Pego1.PeAnnotation.Graph.Color[9] = Color.FromArgb(255, 0, 0, 0);
Pego1.PeAnnotation.Graph.Text[9] = "";

// Place a paragraph of text //
Pego1.PeAnnotation.Graph.X[10] = 0;
Pego1.PeAnnotation.Graph.Y[10] = 0;
Pego1.PeAnnotation.Graph.Type[10] = (int) GraphAnnotationType.StartText;
Pego1.PeAnnotation.Graph.Color[10] = Color.Black;
Pego1.PeAnnotation.Graph.Text[10] = "A line of text." + '\n';

Pego1.PeAnnotation.Graph.X[11] = 0;
Pego1.PeAnnotation.Graph.Y[11] = 0;
Pego1.PeAnnotation.Graph.Type[11] = (int) GraphAnnotationType.AddText;
Pego1.PeAnnotation.Graph.Color[11] = Color.Black;
Pego1.PeAnnotation.Graph.Text[11] = "Col1 Col2" + '\n';

Pego1.PeAnnotation.Graph.X[12] = 0;
Pego1.PeAnnotation.Graph.Y[12] = 0;
Pego1.PeAnnotation.Graph.Type[12] = (int) GraphAnnotationType.AddText;
Pego1.PeAnnotation.Graph.Color[12] = Color.Black;
Pego1.PeAnnotation.Graph.Text[12] = "on off" + '\n';

Pego1.PeAnnotation.Graph.X[13] = 7.75;
Pego1.PeAnnotation.Graph.Y[13] = 1050;
Pego1.PeAnnotation.Graph.Type[13] = (int) GraphAnnotationType.Paragraph;
Pego1.PeAnnotation.Graph.Color[13] = Color.FromArgb(255, 88, 88, 88);
Pego1.PeAnnotation.Graph.Text[13] = "";
Pego1.PeAnnotation.Graph.Font[13] = "Courier New";

// Draw an Arrow Pointer annotation //
Pego1.PeAnnotation.Graph.X[14] = 2.5;
Pego1.PeAnnotation.Graph.Y[14] = 1130;
Pego1.PeAnnotation.Graph.Type[14] = (int) GraphAnnotationType.PointerArrowMedium;
Pego1.PeAnnotation.Graph.Color[14] = Color.FromArgb(255, 0, 198, 198);
Pego1.PeAnnotation.Graph.Text[14] = "Move toward Start";
Pego1.PeAnnotation.Graph.Shadow[14] = true;

// Draw an Arrow annotation //
Pego1.PeAnnotation.Graph.X[15] = 1.5;
Pego1.PeAnnotation.Graph.Y[15] = 1250;
Pego1.PeAnnotation.Graph.Type[15] = (int) GraphAnnotationType.ThinSolidLine;
Pego1.PeAnnotation.Graph.Color[15] = Color.FromArgb(128, 128, 200, 198);
Pego1.PeAnnotation.Graph.Text[15] = "";

Pego1.PeAnnotation.Graph.X[16] = 2.5;
Pego1.PeAnnotation.Graph.Y[16] = 1290;
Pego1.PeAnnotation.Graph.Type[16] = (int) GraphAnnotationType.ArrowSolidSmall;
Pego1.PeAnnotation.Graph.Color[16] = Color.FromArgb(128, 128, 200, 198);
Pego1.PeAnnotation.Graph.Text[16] = "";

// Place a symbol on right y axis //
Pego1.PeAnnotation.Graph.X[17] = 11.5;
Pego1.PeAnnotation.Graph.Y[17] = 900;
// 1000 in following line designates right y axis
Pego1.PeAnnotation.Graph.Type[17] = (int) GraphAnnotationType.SmallDotSolid + 1000;
Pego1.PeAnnotation.Graph.Color[17] = Color.FromArgb(255, 88, 88, 88);
Pego1.PeAnnotation.Graph.Text[17] = "900 Right Axis";
Pego1.PeAnnotation.Graph.GradientStyle[17] = (int) PlotGradientStyle.RadialTopLeft;
Pego1.PeAnnotation.Graph.Shadow[17] = true;

// Draw Angled Text Annotation //
Pego1.PeAnnotation.Graph.X[18] = 1.5;
Pego1.PeAnnotation.Graph.Y[18] = 1250;
Pego1.PeAnnotation.Graph.Type[18] = (int) GraphAnnotationType.NullPen;
Pego1.PeAnnotation.Graph.Color[18] = Color.FromArgb(0, 0, 0, 0);
Pego1.PeAnnotation.Graph.Text[18] = "";

Pego1.PeAnnotation.Graph.X[19] = 2.5;
Pego1.PeAnnotation.Graph.Y[19] = 1290;
Pego1.PeAnnotation.Graph.Type[19] = (int) GraphAnnotationType.AngledText;
Pego1.PeAnnotation.Graph.Color[19] = Color.FromArgb(255, 88, 88, 88);
Pego1.PeAnnotation.Graph.Text[19] = "Hello";

// Show annotations shadows //
Pego1.PeAnnotation.Graph.ShowShadows = true;

// Allow user to move ArrowPointer annotation //
Pego1.PeAnnotation.Graph.Moveable = true;
Pego1.PeUserInterface.HotSpot.GraphAnnotation = AnnotationHotSpot.GraphOnly;

 

Non-orthogonal and complex line drawing can be accomplished with a MoveTo/LineTo style mechanism.

 

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.

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. 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.  See demo example 015.

 

 

Line Annotations

Horizontal lines can be added with the following properties:

 

HorzLineAnnotation

Y location of line annotation.

HorzLineAnnotationType

Line type.

HorzLineAnnotationText

Text associated with this annotation. Can include various justification codes.

HorzLineAnnotationColor

Color of annotation.

HorzLineAnnotationAxis

Axis location (0 - 5) if using Multi-Axes.

HorzLineAnnotHotSpot

Non-Zero to designate annotation as a hot spot.

 

Vertical lines can be added with the following properties:

 

VertLineAnnotation

X location of line annotation.

VertLineAnnotationType

Line type.

VertLineAnnotationText

Text associated with this annotation. Can include various justification codes.

VertLineAnnotationColor

Color of annotation.

VertLineAnnotHotSpot

Non-Zero to designate annotation as a hot spot.

 

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. 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.

 

Pego1.PeAnnotation.Line.YAxis[0] = 955;
Pego1.PeAnnotation.Line.YAxisType[0] = LineAnnotationType.ThinSolid;
Pego1.PeAnnotation.Line.YAxisText[0] = "|RRight Text";
Pego1.PeAnnotation.Line.YAxisColor[0] = Color.FromArgb(255, 255, 255, 255);

 

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 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.

 

Pego1.PeAnnotation.Line.RightMargin = "Right Text";
Pego1.PeAnnotation.Line.YAxisShow = true;

 

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 similar to above GraphAnnotation code.

 

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 or use AutoMinMaxPaddingY to assure axis annotation text does not conflict with your plotted data.

 

Axis annotations consist of:

 

XAxisAnnotation

X location of axis annotation.

XAxisAnnotationText

Text of annotation.

XAxisAnnotationColor

Color of annotation.

YAxisAnnotation

Y location of axis annotation.

YAxisTextAnnotations

Text of annotation.

YAxisAnnotationColor

Color of annotation.

 

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.

 

Pego1.PeAnnotation.Axis.TextSize = 125; // 1.25 times normal

Pego1.PeAnnotation.Axis.XText[0] = "XAxis 1.3";
Pego1.PeAnnotation.Axis.X[0] = 1.3;
Pego1.PeAnnotation.Axis.XText[1] = "XAxis 1.4";
Pego1.PeAnnotation.Axis.X[1] = 1.4;
Pego1.PeAnnotation.Axis.XText[2] = "XAxis 1.5";
Pego1.PeAnnotation.Axis.X[2] = 1.5;
Pego1.PeAnnotation.Axis.XText[3] = "XAxis 1.6";
Pego1.PeAnnotation.Axis.X[3] = 1.6;

Pego1.PeAnnotation.Axis.XText[4] = "XAxis 2.40";
Pego1.PeAnnotation.Axis.X[4] = 2.4;
Pego1.PeAnnotation.Axis.XText[5] = "XAxis 2.45";
Pego1.PeAnnotation.Axis.X[5] = 2.45;
Pego1.PeAnnotation.Axis.XText[6] = "XAxis 2.50";
Pego1.PeAnnotation.Axis.X[6] = 2.5;
Pego1.PeAnnotation.Axis.XText[7] = "XAxis 2.55";
Pego1.PeAnnotation.Axis.X[7] = 2.55;

Pego1.PeAnnotation.Axis.XShow = true;

 

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