Getting Started

Files you need

Note: For the purposes of this documentation, DPlot and DPlot Jr are used interchangeably unless there are clear differences.

  • DPLOT.EXE or DPLOTJR.EXE. Whether your application will use DPLOTLIB to create plots within DPlot as a standalone application or display plots created by DPlot within a window of your own application, you will need either the full version of DPlot or DPlot Jr. The DPLOTLIB DLL simply acts as an interface between your program and DPlot; it does not perform any graphics operations by itself. You can get the setup program for DPlot Jr from the DPlot web site. The direct link to the DPlot Jr setup program is http://www.dplot.com/dplotjr_setup.exe. Licensed users of the full version of DPlot should sign up for the mailing list to ensure that you have the latest version of the program.

    What's the difference? DPlot Jr is free and may be distributed without royalty payments or any other fees. However, it lacks many of the features of the full version. In particular you cannot open a file with DPlot Jr, either within the program or programmatically. DPlot Jr also lacks many of the data generation and analysis features of the full version; e.g. FFT, curve fitting, generating a curve or surface from an equation, etc. For many applications, though, you'll find DPlot Jr adequate for your needs. The full version of DPlot cannot be distributed to end users of your application without a developer license. Contact us for more information on a developer license for the full version.

    NOTE: This version of DPLOTLIB requires version 1.97 or later of DPlot or DPlot Jr. Earlier versions will not work properly with all functions. Check the version number of either program with the About command on the Help menu. If you do not have the minimum version number, you can get them by following the instructions above.
     

  • DPLOTLIB.DLL. This library handles all of the communication between your application and DPlot. It is included with the DPlot Jr distribution; all files related to dplotlib.dll are installed to the \dplotlib folder below DPlot Jr. The default installation folder is c:\Program Files\DPlotJr. If you have already downloaded and installed DPlot Jr, you do not need any additional files. If you instead are working only with the full version of DPlot, you can get the DPLOTLIB files from http://www.dplot.com/lib/dplotlib.zip. Unzip this file to the folder of your choice, making sure that "Use folder names" is checked so that you preserve the folder structure within the ZIP file.
     
  • Interface files. These files describe the calling convention and argument list to your compiler.
    • Visual Basic 6: global.bas in the \btest folder. Add this file to your project with Project>Add Module.
    • Visual Basic .NET: global.vb in the \vbnet folder. Add this file to your project with Project>Add Module.
    • PowerBasic: dplot.inc in the \pb folder. Include in your project with #INCLUDE "dplot.inc".
    • FreeBASIC: fb-dplotlib.bi in the \freebasic folder. Include in your source with #INCLUDE "fb-dplotlib.bi".
    • C (all currently supported compilers: Microsoft Visual C, Borland, LCC, GCC): #include dplot.h, found in the \c folder.
    • C#: dplot.cs located in the \csharp folder. Add this file to your project with Add>Existing Item.
    • FORTRAN: dplot.fi in the project folder for each supported FORTRAN. Note that these files are, in almost all cases, not interchangeable between various FORTRAN compilers.

     
  • Import library. Irrelevant for Visual Basic, Visual Basic .NET, and C#. For other environments, if you will be statically linking to dplotlib.dll (as opposed to using LoadLibrary and GetProcAddress at runtime) you will need to link to the appropriate import library. Otherwise you will get "unresolved external" errors on DPLOTLIB functions when linking. For the currently supported languages and compilers, the import library dplotlib.lib can be found in the project folder for your language. For example if using Microsoft Visual C, use the file \c\msvc\dplotlib.lib.

    Other Compilers/Languages
    Many compilers will link properly with the import library dplotlib.lib found in the \c\msvc folder. Others may require that you build an import library from the compiled DLL using a compiler-specific tool. If you search your compiler's documentation for "import library" you will likely find the information necessary to build an import library from dplotlib.dll. Requests for support of additional languages/compilers will at the very least be considered; if you have such a request contact the author at support@dplot.com.

    For languages that support it (C, for example), you can alternatively resolve all DPLOTLIB references at runtime rather than linking to an import library by using LoadLibrary and GetProcAddress. A thorough explanation of the technique is beyond the scope of this documentation. The gcc example programs use this technique; see the end of the header file dplot.h in the \c folder for more information.

Where does DPLOTLIB.DLL go?

Wherever you want, as long as your program can find it. Many Windows applications install DLLs to the Windows System folder. Although this will work (your application, or more correctly Windows, will find the DLL with no special effort), we strongly advise against doing this with dplotlib.dll. Although you can certainly ensure that you do not overwrite new copies of the DLL with an old version, there is no way to guarantee that another developer will be as well-behaved. When searching for DLLs Windows will always look in the application folder (the folder where your compiled executable resides) first. This is true whether statically linking to a DLL using an import library, or dynamically linking at runtime using a call to LoadLibrary. So the simplest thing to do is copy dplotlib.dll to the folder where your executable will reside. This will work correctly for all compiled executables, regardless of the language or compiler used by your program.

For running your application within the development environment (for example Visual Basic 6, VB.NET, or C#) you will need to take one extra step. That is because, at least in the case of VB 6, the "application folder" in this case is not the folder where your project resides, but the folder where your development tools reside. But, as luck would have it, the second place Windows looks for DLLs is in the "working directory", which can be controlled programmatically. In your Form_Load event, you should call the procedure DPlot_FindDPLOTLIB. The code for this procedure is located in global.bas for VB projects, global.vb for VB.NET projects, and dplot.cs for C# projects. DPlot_FindDPLOTLIB first attempts to load dplotlib.dll using the Windows API function LoadLibrary. If successful, there's no need to do anything else and the subroutine exits. If LoadLibrary fails (which it most likely will when running your program within VB), DPlot_FindDPLOTLIB checks the registry for the location of the DLL. This location (HKEY_CURRENT_USER\Software\DPLOT\DPLOTLIB\Folder) was created when DPlot and/or DPlot Jr were installed. When that path is retrieved from the registry, DPlot_FindDPLOTLIB sets the working directory to that path. Of course in the case of VB.NET and C# you can also get around this problem by copying dplotlib.dll to the \bin\debug folder for your project - DPlot_FindDPLOTLIB is provided so that you don't need to do that.

What's next?

We strongly suggest taking a look at the example programs (described on the following page) before diving in with your own application. The simplest examples generate data and pass that data to DPlot using the DPlot_Plot function. Those are the VB6 btest.vbp project in \btest, the VB.NET project in \vbnet\Project1.NET, the ctest.c C example located in \c, and the test1 C# project in \csharp\test1. (All FORTRAN examples perform these same basic functions).

 

 
Previous Home Next DPlot Home