Visit Gigasoft's Web Site
 ProEssentials v9 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.




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.



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









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

CopyFrom(float[,] source)

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

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.

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.