Visit Gigasoft's Web Site
 ProEssentials v10 Help

Chapter 2: .NET and Property Arrays

 

The Basics

Property arrays are properties and/or data items like PeData.Y, PeString.SubsetLabels, PeColor.PointColors, and many others that have multiple values defined by one or two indices. These property arrays are dynamic in that they grow as you increase the indices used to set items. Some property arrays have default elements defined and others are empty by default.

 

Some examples of property arrays with default elements are PePlot.SubsetLineTypes, PePlot.SubsetPointTypes, and PeColor.SubsetColors.

 

Some examples of property arrays empty by default are PeData.RandomSubsetsToGraph, PeLegend.SubsetsToLegend, and PeGrid.MultiAxesSubsets.

 

The C# syntax for setting property arrays is like...

Pego1.PeData.Y[nSubetIndex, nPointIndex] = fDataValue;

 

The Visual Basic syntax for setting property arrays is like...

Pego1.PeData.Y(nSubetIndex, nPointIndex) = fDataValue

 

Similar syntax is used with one dimensional property arrays and when getting/retrieving values.

 

It is important to realize that a property array has a size and this size is often used to control image construction. If you are providing some form of user interface or report procedure, you may be continuously manipulating property arrays. If they grow dynamically, you also need a way to shrink or empty the property array. This can be accomplished using the Clear method. For example, RandomSubsetsToGraph is a common property array that needs to be emptied or resized. The following code shows how to empty this property array.

 

Pego1.PeData.RandomSubsetsToGraph.Clear()

 

You can determine the total size of a property array with the Length() method.

 

Also note that PeFunction.Reset() will empty the control of all property settings and revert the object to its default state. This is easier and the recommended approach when you need to reset the state of the object due to repeatedly changing the object.

 

Regarding Jagged Data, PeData.JaggedData set to True.

 

Use PeData.GetJaggedPointsX and similar functions to get the size (number of data Points) of jagged array.

Use PeData.SetJaggedPointsX and similar functions to set the size of jagged array.

It is not necessary to set the size of a array as the array will grow automatically, but setting the size may help with memory reallocations if spoon-setting large amounts of data.

 

 

 

Property Array Basics

The technology behind property arrays is known as Indexers.  These are special .NET classes to facilitate working with dynamic lists using common array nomenclature.

 

ProEssentials defines some common Indexers to work with different types of property arrays. You will never allocate these classes yourself, but inherently use them as embedded features.  You may see mention of these classes when working with ProEssentials. Just note they are internal mechanisms to facilitate working with arrays. The more commonly used classes include...

 

OneDimensionalFloatArray

TwoDimensionalFloatArray

OneDimensionalDoubleArray

TwoDimensionalDoubleArray

OneDimensionalStringArray

TwoDimensionalStringArray

 

The Indexers classes above also contain a few more methods which you may find useful...

 

GetLength(int dimension)

Determines the size of individual dimensions for two dimensional arrays.
Possible dimension settings are:
- 0, gets size of first dimension.
- 1, gets size of the second dimension.

Clear(int newSize)

Sets the new size of a property array.  Truncating its size and losing all elements past newSize.

Initialize(float dataValue)

Fills array with the provided data value.  Useful to initialize array with a user defined null data value. If needed, the size of array should first be set by simply setting the last element in the array.

FastCopyFrom(float[,] source)

Available only with data property arrays. Copies elements from a 2 dimensionals array into this array. The size of the dimensions must be PeData.Subsets by PeData.Points.  This methods calls ProEssentials.Api.PEvset which block copies the source bytes directly into the chart.

FastCopyFromJagged(float[] source, int nSubset)

For when JaggedData = True, Copies elements from a one dimensional source array into the subset nSubset and sets the size of this subset. Only use for X, Xii,Y, Yii, Z, Zii, and PointColors property arrays when JaggedData = True.

CopyFrom(float[,] source)

Available only with data property arrays. Copies elements from a 2 dimensional source array into this array. The size of the dimensions must be PeData.Subsets by PeData.Points.

CopyFromJagged(float[] source, int nSubset, int nElements = 0)

For when JaggedData = True, copies elements from a single dimension source array into the subset array nSubset and sets the size of this subset. Only use for X, Xii,Y, Yii, Z, Zii, and PointColors property arrays when JaggedData = True.

float[,] Copy()

Available only with data property arrays. Copies this array to another array. The size of the dimensions will be PeData.Subsets by PeData.Points.

float[] CopyJagged(int nSubset)

For when JaggedData = True, copies the array for subset nSubset to another array. Only use for X, Xii,Y, Yii, Z, Zii and PointColors property arrays when JaggedData = True.

int BindData(IEnumerable source,

  int startingSubsetIndex,

  int startingPointIndex)

Available only with data property arrays. Loads data from a DataReader or DataView source.  This method does not clear existing data or alter PeData.Subsets and PeData.Points.  This method will fill this array with data up-to an amount defined by PeData.Subsets and PeData.Points.  Data is loaded at indices starting with startingSubsetIndex and startingPointIndex. Multiple subsets of data are read in and allocated by their sequence in column. The return value is the number of records set.