For a list of DLL functions and general DLL type information, see within the left-frame: Contents tab / ProEssentials Reference / Alphabetic Listing / SDK/DLL Functions. Even though you may not be developing with the .NET interfaces, the .NET Reference is an excellent method of visualizing how the 1000+ properties are organized. Once you drill down to the property level, you will see DLL syntax and information.

Also, even though you may be implementing via the WinForm, WebForm, OCX or VCL interface, you will find the information in this chapter worth knowing. The DLL interface is the most efficient and fundamental building block of Windows software. Any implementation that utilizes the ProEssentials DLL directly will be providing the fastest and/or smallest possible implementation. Using the PEvset function to pass large data-sets can improve WinForm, WebForm, OCX, and VCL interface performance by 10 fold or more when dealing with large data sets. This gives the best of both worlds, easy integration with the IDE, and the fastest data transfer speed.

For help finding DLL features, use the Contents Tab at the top-left location within this help system, near the bottom, click Reference, and then Alphabetic Listing.

All the visual interfaces included within the ProEssentials product get their charting functionality from the DLL.  The DLL is named differently dependent upon the version purchased.

Just like the .NET Framework wraps the GDIPlus DLL, ProEssentials provides simplified interfaces to our DLL as WinForm, WebForm, OCX, or VCL interfaces. If you are using the WinForm, WebForm, OCX, or VCL interfaces, then 1) any mention of PEcreate or "object creation" is handled by the respective visual interface and you won't normally call PEcreate/PEdestroy; 2)  If you never expect to call a DLL call, you can skip the remainder of this section.

ProEssentials DLL interface is very small in that it only has a handful of commonly used functions. These functions are PEcreate, PEdestroy, PEnset, PEszset, and PEvsetcell.

PEcreate is similar to the Windows CreateWindow function. However, it always creates a child window and places this child into the provided parent. The PEcreate function returns the Windows handle for the newly created control and this handle must be used to set properties and eventually destroy the control. As with most child windows, the ProEssentials controls will communicate with its parent through WM_COMMAND notification messages. For every call to PEcreate, there must be a call to PEdestroy. This function destroys the child window and frees memory and resources. PEnset is used to set integer (PEP_n), boolean (PEP_b), dword (PEP_dw), and handle (PEP_h) properties. PEszset is used to set null-terminated-string properties (PEP_sz). PEvsetcell is used to set property arrays like data-values and data-labels (PEP_fa, PEP_na, PEP_sza).

ProEssentials' function and property reference material refer to data types of INT, UINT, and BOOL. These include properties that start with PEP_b, PEP_dw, PEP_h, and PEP_n. These property types are all considered Long Integers (32 bits).

Working with Properties and Data

There are several methods of establishing and maintaining properties.

1) The developer uses PEvset and PEvget to set or get property arrays and any other property of non-simple data type like float, double, and structures like RECT and POINT.

2) PEvsetcell and PEvgetcell are used to access individual elements of one-dimensional property arrays.

3) PEvsetcellEx and PEvgetcellEx are used to acess individual elements of two-dimensional property arrays.

4) PEnset and PEnget are used to access all simple type propertie; integer, boolean, handle, and double-word.

5) PEszset and PEszget are used to access all string properties. Note, PEszsetA and/or PEszsetW may be called to work specifically with short-char or wide-char data, else the presence of the UNICODE pragma will control if PEszset automatically maps to PEszsetA or PEszsetW. .

6) PEvsetEx and PEvgetEx functions are used to partially set or get a property array.

Within the property reference material, at the top of each property topic, you'll see a table with various property attributes.  For example, the property FontSize has such an entry.

If developing with the DLL interface, you'll refer to this property via the DLL row heading.

For a control with handle m_hPE, to programmatically control the FontSize property within code, you'll write...

WIN32 Implementation

The creation procedure will usually be implemented in response to the WM_INITDIALOG, or WM_CREATE message. This means for MFC developers, place creation code into the OnInitDialog or OnCreate override.

1) Declarations and constant definitions.

 C/C++ developers, include the file "PEGRPAPI.H". This file contains function declarations and constant definitions.  Also, the linker needs to find "PEGRP32D.LIB".  These are both located in the "C:\ProEssentials6\VC" directory. Note if using Standard or Lite versions, the LIB is "PEGRPDS.LIB" or "PEGRPDL.LIB"

VB6 developers can find the declarations in "PE6API.BAS".

 Delphi developers can find these declarations and definitions in the file "PEGRPAPI.PAS". You can access any of the functions or constants by adding [Pegrpapi] to your uses clause. This is true whether you are using the VCL interfaces or not.

2) Control construction.

Call function PEcreate to create the object. PEcreate returns the window handle to the object. This handle needs to be placed in permanent storage. This handle is used in both Windows and ProEssentials API calls.  All that's needed to see a chart is PEcreate.  

3) Set properties that control the look and operation of the control.

 Use PEnset, and PEszset to set most properties. Two very important properties are those establishing the number of subsets and points (per-subset) that the object will manage (Subsets, and Points). Set these two properties first. PEvset is used to set floating point type properties. When using PEvset, pay close attention to the floating point type you are pointing to. Most properties are double precision (double) but there are a few that are single precision (float). Making a mistake of pointing to the wrong type of variable can cause unexpected behavior in your application. So, anytime you see PEvset in your program, give this function call more attention.

4) Set property arrays which hold the controls data.

 Use PEvset, PEvsetEx, PEvsetcell, or PEvsetcellEx to transfer data into the object.

PEvset is used to set an entire property arrays content with one function call. Note, it's faster to use PEvsetcell or PEvsetcellEx to pass string arrays, and related to PEvsetcell, set the last index prior to passing the remaining indices for fastest performance.

PEvsetEx is used to set a portion of block data with one function call.

PEvsetcell is used to set individual elements of a one dimensional property array. Set the last index prior to passing the remaining indices for fastest performance.

PEvsetcellEx is used to set individual elements of a two dimensional property array. SubsetLabels, PointLabels, XData, YData, SubsetColors, SubsetLineTypes, and SubsetPointTypes will be the most common property arrays.

You should try to call the PEvset function to transfer all the objects data with one function call. This is always the fastest method of getting data into a graph. This method should definitely be utilized if the number of data-points is greater than 5000.  If using a WinForm, WebForm, OCX or VCL interface, this method is still accessible and should be implemented if possible. .NET, VB6 and Delphi examples of this method are found in the demo, example 018.

PEvsetEx will allow you to pass a partial chunk of a property array rather than the entire property array's content. This is useful if you want to pass just one subsets worth of data all at once.

5) Control re-initialization

 Use PEreinitialize to reset the object to the newly adjusted properties and data.

 Use PEresetimage to reset the object's image.

 The reason two functions are required is because PEreinitialize performs variable initialization, and PEresetimage constructs the image. PEresetimage takes more time and is much more involved than PEreinitialize. To show the advantage of this approach, lets consider an example. Say you wanted to add annotations that were related to the scale of the graph. You can initialize the objects data and other properties, call PEreinitialize which will determine the graph's scale. Look at the ManualMinY and ManualMaxY properties and add your annotations as needed with respect to these units. Finally, call PEresetimage to complete the object's initialization. This prevents the image from having to be generated twice. When dealing with large data sets, this can be a significant time saver.

6) Finishing touches

 If tab order needs to be adjusted then use the Windows SetWindowPos function to set the Z-Order.

Finally!

When the object needs to be deleted call PEdestroy. Responding to WM_CLOSE is a good location to call PEdestroy.