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