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 1200+ 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 WPF, 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 WPF, WinForm, WebForm, OCX, and VCL interface performance by 100
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
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.
ProEssentials v8 Pro
ProEssentials v8 Standard
ProEssentials DLL interface is very small in that it only has a handful
of commonly used functions. These functions are PEcreate,
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,
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.
All ProEssentials Objects.
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...
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 "PEGRP32F.LIB". These
are both located in the "C:\ProEssentials8\VC"
directory. Note if using Standard, the LIB is "PEGRPSF.LIB"
VB6 developers can find the declarations in "PE8API.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
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,
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 WPF, WinForm, WebForm, OCX or VCL interface, this method is still accessible
and should be implemented if possible. .NET, 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
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.
When the object needs to be deleted call PEdestroy.
Responding to WM_CLOSE or WM_DESTROY is a good location to call PEdestroy.