Visit Gigasoft's Web Site
ProEssentials v8 Help

Chapter 6: Creating Custom Scales

 

This topic discusses the use of annotations and events to create a custom scale.

 

Using Line Annotations to create a scale

Disable the default scale and replace it with your own tick marks and/or grid lines defined with line annotations.

 

Also refer to demo project example 005 on creating custom scales.

 

For custom y axes:

HorzLineAnnotation

Y location of line annotation.

HorzLineAnnotationType

Line type, generally GridTick(7) or GridLine(8)

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.

 

For custom x axes:  

VertLineAnnotation

X location of line annotation.

VertLineAnnotationType

Line type, generally GridTick(7) or GridLine(8)

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.

 

Custom scales generally use special line annotation types of...

  • PELAT_GRIDTICK 7

  • PELAT_GRIDLINE 8 - color of mark defined by GraphForeColor

  • PELAT_GRIDTICKII 14 - annotation color is applied

  • PELAT_GRIDLINEII 15

These annotation types will create tick marks and grid lines as needed. They will function as normal grid lines and can be controlled by the user via the GridLineControl user customization, or by the developer with the GridLineControl property.

 

For more information on adding annotations to a chart, See Chapter 6 Annotations.

 

The following example shows how to create a simple textual y axis.

 

// Disable default scale //
Pego1.PeGrid.Option.ShowYAxis = ShowAxis.Empty;


// Generally, a custom y axis will need manual range control //
Pego1.PeGrid.Configure.ManualScaleControlY = ManualScaleControl.MinMax;
Pego1.PeGrid.Configure.ManualMinY = 0.0;
Pego1.PeGrid.Configure.ManualMaxY = 1500.0;


// Create custom grid lines with HorzLineAnnotations //
// Note that GridLineControl will control these annotations //
Pego1.PeAnnotation.Line.YAxis[0] = 200;
Pego1.PeAnnotation.Line.YAxisType[0] = LineAnnotationType.GridLine;
Pego1.PeAnnotation.Line.YAxisText[0] = "|LLow Value";

Pego1.PeAnnotation.Line.YAxis[1] = 700;
Pego1.PeAnnotation.Line.YAxisType[1] = LineAnnotationType.GridLine;
Pego1.PeAnnotation.Line.YAxisText[1] = "|LMedium Value";

Pego1.PeAnnotation.Line.YAxis[2] = 1400;
Pego1.PeAnnotation.Line.YAxisType[2] = LineAnnotationType.GridLine;
Pego1.PeAnnotation.Line.YAxisText[2] = "|LHigh Value";

Pego1.PeAnnotation.Line.YAxis[3] = 450;
Pego1.PeAnnotation.Line.YAxisType[3] = LineAnnotationType.GridTick;
Pego1.PeAnnotation.Line.YAxisText[3] = "";

Pego1.PeAnnotation.Line.YAxis[4] = 1050;
Pego1.PeAnnotation.Line.YAxisType[4] = LineAnnotationType.GridTick;
Pego1.PeAnnotation.Line.YAxisText[4] = "";


// Set LeftMargin to allocate space for line annotation text //
// Use the longest string used in annotations.
Pego1.PeAnnotation.Line.LeftMargin = "Medium Value ";


// Set this to see annotations //
Pego1.PeAnnotation.Show = true;


// Increase line annotation text size //
Pego1.PeFont.LineAnnotationTextSize = 100;


// Put Grid In Front of Bars and remove banding //
Pego1.PeGrid.GridBands = false;
Pego1.PeGrid.InFront = true;

 

The following image is produced by the above code.

Note the three labels on left y axis.

 

This example first disables the default y axis with ShowYAxis.

 

Next, it manually chooses a range for the new y axis. This new range will be from 0 to 1000.

 

Next, three grid-line annotations are added at coordinates of 200, 700, and 1400 within the 0 to 1500 axis range. Note that the HorzLineAnnotationText items are using justification codes "|L" to place text on the outside left edge. Refer to HorzLineAnnotationText for more info on justifying line annotation text.

 

Next, two grid-tick annotations are added at coordinates 450 and 1050. Note that the text for these annotations is a empty string.

 

Next, the LeftMargin property is set. This is a textual property which should be set to the largest string used for any annotation text. ProEssentials will use this example text to determine the amount of space to reserve for line annotations placed on the outside left edge of the chart. It's usually a good idea to make this text string slightly larger by a few characters. Related is ShowMargins.

 

Finally, ShowAnnotations is set to true, LineAnnotationTextSize will generally be set to 100, and the grid is placed in front with GridInFront.

 

 

 

Using the CustomGridNumber Event

This method of creating a custom scale uses an event to allow the developer opportunity to change the textual representation of a data value.

 

You set one or more of the following properties to true to enable event processing:

 

CustomGridNumbersY

Enable custom Y axis.  

CustomGridNumbersX

Enable custom X axis.

CustomGridNumbersRY

Enable custom Right Y axis.

CustomGridNumbersTX

Enable custom Top X axis.

CustomGridNumbersZ

Enable custom Z axis.

 

Please refer to demo project example 132 on seeing the specifics of handling the CustomGridNumber event within the development language of your choice.

The code below sets up two axes and overlaps, then for the second axis (WorkingAxis= 1), it sets the CustomGridNumbersY flag to True;

With this flag set, the PeCustomGridNumber event will fire and your code can inject formatting as desired. The code below looks for a few specific values and replaces the string.
Pesgo1.PeGrid.MultiAxesSubsets[0] = 2;
Pesgo1.PeGrid.MultiAxesSubsets[1] = 2;
Pesgo1.PeGrid.OverlapMultiAxes[0] = 2;

Pesgo1.PeGrid.WorkingAxis = 0;
Pesgo1.PeColor.YAxis = Color.FromArgb(150, 0, 198, 0);
Pesgo1.PeString.YAxisLabel = "Not Formatted";

Pesgo1.PeGrid.WorkingAxis = 1;
Pesgo1.PeColor.YAxis = Color.FromArgb(150, 0, 198, 198);
Pesgo1.PeString.YAxisLabel = "Formatting this Axis";
// Enable formatting events for second y axis as WorkingAxis is currently 1
Pesgo1.PeGrid.Option.CustomGridNumbersY = true;

/////////////////////////////////////////////////////////
// From the CustomGridNumbers event /////////////////////
/////////////////////////////////////////////////////////
void Pesgo1_PeCustomGridNumber(object sender, CustomGridNumberEventArgs e)
{
  if(e.AxisType == 0)
  {
  // Left Y Axis //
  if(e.NumberValue == -400.0F)
     e.NumberString = "Low Value";
  else if(e.NumberValue == -200.0F)
     e.NumberString = "Medium Low Value";
  else if (e.NumberValue == 0.0F)
     e.NumberString = "Medium Value";
  else if (e.NumberValue == 200.0F)
     e.NumberString = "Medium High Value";
  else if (e.NumberValue == 400.0F)
     e.NumberString = "High Value";
  }
}



Now, zooming this chart, note how the scales are dynamically changed in frequency, yet the custom grid labels still apply.