DPlot_Start function

HWND DPlot_Start(int Hide, int *was_active);

Parameters

Hide

If non-zero, DPlot will be invisible to the user. This is the same state used by DPlot_PlotBitmap and DPlot_PlotToRect if DPlot is not already running when those functions are called. If 0, DPlot is started normally (if it is not already running).

See notes below on the Hide argument.

*was_active

Address of an integer value that receives 1 if DPlot was already running and 0 if it was not. If this parameter is set to NULL, no value is returned.

Return Values

0	Could not start DPlot, or found that the wrong version number is installed on the user's system. In the latter case the user will be presented with a dialog explaining the problem.
>0	Window handle of the main DPlot application window.

Remarks

It is never mandatory to call DPlot_Start, since all routines that interact with DPlot will start it if it is not already running. However, two routines (DPlot_PlotBitmap and DPlot_PlotToRect) will shut DPlot down when finished if DPlot was not already active. If your application uses either of these routines then performance will be improved considerably if you call DPlot_Start when your application is first activated.

DPlot_Start first checks the minimum version criteria. The minimum version can be set with a call to DPlot_MinVersion. If DPlot_MinVersion is not first called, the minimum required for this version of DPLOTLIB.DLL (2.0.0.3) is used. If DPlot Jr is installed and meets this minimum version requirement but the full version does not, then DPlot Jr will be used regardless of whether the full version of DPlot is installed or running. If neither DPlot Jr nor the full version of DPlot meet the minimum version requirement, an error message similar to that shown below will be presented.

If you do not want this error message to be displayed to your users, you should first call DPlot_MinVersion and handle the situation within your own program if that function returns 0.

The search for and decision of which program to use proceeds as follows (in all cases assuming that both programs meet the minimum version criteria). The search stops with an affirmative answer at any step.

1) Use FindWindow to see if DPLOT.EXE is running.

2) Use FindWindow to see if DPLOTJR.EXE is running.

3) Look in the registry for the path to DPLOT.EXE at HKEY_CURRENT_USER/Software/DPlot.

4) Look in the registry for the path to DPLOT.EXE at HKEY_LOCAL_MACHINE/Software/DPlot.

5) Look in the registry for the path to DPLOTJR.EXE at HKEY_CURRENT_USER/Software/DPlotJr.

6) Look in the registry for the path to DPLOTJR.EXE at HKEY_LOCAL_MACHINE/Software/DPlotJr.

If you want to be able to test DPlot Jr and also have the full version of DPlot installed on your system, you can force DPLOTLIB to use DPlot Jr by deleting the registry entry(s) for DPlot (HKEY_CURRENT_USER/Software/DPlot and, if it exists, HKEY_LOCAL_MACHINE/Software/DPlot). The HKEY_CURRENT_USER entry is recreated every time DPlot is started, so you do not risk fouling things up by deleting it.

Hide argument

If DPlot_Start is called with a non-zero Hide argument, then you should ensure that your application shuts DPlot down, first by closing any documents that your application created, then with a call to DPlot_Stop before exiting. Otherwise DPlot will continue to run, consuming resources on the end user's system. Methods for stopping DPlot from various development environments follow:

C	Call DPlot_Stop in response to WM_DESTROY message in a dialog procedure, or before returning from WinMain.
VB 5/6	Call DPlot_Stop in the Form_Terminate procedure.
C#	In the Form.Designer module, call DPlot_Stop in the namespace's Dispose routine, for example: protected override void Dispose(bool disposing) { if (disposing && (components != null)) { components.Dispose(); } base.Dispose(disposing); dplot.DPlot_Stop(); }
VB.NET	Call DPlot_Stop in the Dispose routine of your form's Windows Form Designer generated code section: Protected Overloads Overrides Sub Dispose(ByVal Disposing As Boolean) If Disposing Then If Not components Is Nothing Then components.Dispose() End If End If MyBase.Dispose(Disposing) DPlot_Stop() End Sub

NOTE: If the Hide argument is non-zero, DPlot (or DPlot Jr) are already running, but there are no currently open documents, then DPlot (or DPlot Jr) will be hidden and the was_active parameter will be set to 0 (indicating that DPlot was not running, though in truth it was).

Regardless of your development environment, you can test to ensure that DPlot was properly shut down with the Windows Task Manager: Press Ctrl+Alt+Del, select Task Manager, select the Processes tab, and search for DPLOT.EXE in the Image Name column. If it is there, then your program still needs a little work.

Page url: http://www.dplot.com/lib/index.htm?dplot_start.htm