Navigation:  Programmer's Reference > Plugins JR   Viewer

Plugins are separate modules (DLL’s) that add functionality to DPlot. DPlot supports three types of plugin: file import for file formats not supported by DPlot, file export for both data files and image formats, and “generate” plugins for manipulating existing data in some way. DPlot Jr users please note: DPlot Jr supports file export plugins only. It does not support file import or generate plugins.

Sample plugins (file import and generate) are available on the Download page at the main DPlot web site. C source code is provided along with the plugin DLL’s. The comments within the source code explain in some detail what is needed; the pointers below are included for emphasis. Constants shown below, e.g. "DATA_3D", are defined in the file dplot.h distributed with the example plugins.

Plugin modules should be placed below the folder where dplot.exe is located (default=c:\Program Files\DPlot) in the \plugins\fileimport, \plugins\fileexport, or \plugins\generate folders. Generate plugins may also be placed in subfolders below \plugins\generate. In that case the subfolder name will be used as a popup menu item on the Generate menu.

File Import functions

plugin_init is called by DPlot at startup.

__declspec(dllexport) int plugin_init( char *Desc,
                                      char *DefExt,
                                      int *DataType )

 

Return value from plugin_init should be PLUGIN_INIT_OK plus (optionally) PLUGIN_INIT_MULTIFILE if the user should be allowed to select multiple files to open prior to reading the files (one at a time) with plugin_readfile. Note that DPlot will ignore PLUGIN_INIT_MULTIFILE for 3D data.

plugin_version returns the version number of the DPLOT structure expected in subsequent calls to plugin_readfile. This function is required for structure versions 3 and later, and optional for earlier versions. See notes below.

__declspec(dllexport) int plugin_version()

plugin_readfile reads a file.

__declspec(dllexport) int plugin_readfile( HWND hwndOwner,
                                          char Filename,
                                          DPLOT *DPlot,
                                          float *Data1,
                                          float *Data2)

 

Since plugin_readfile may be called for either an empty document or to append data to a document, it must take note of the NumCurves entry in the DPlot structure for DATA_XYXY. The X and Y arrays will already point to the first available curve, but entries in the DPlot structure are for the entire document.

plugin_readfileex is identical to plugin_readfile with the addition of an "Options" string in the argument list. A file import plugin should include either plugin_readfile or plugin_readfileex, but not both. plugin_readfileex requires DPlot version 1.9.8.4 or later.

__declspec(dllexport) int plugin_readfileex( HWND hwndOwner,
                                            char Filename,
                                            DPLOT *DPlot,
                                            float *Data1,
                                            float *Data2,
                                            LPSTR Options)

For file import plugins distributed with DPlot, these options (when present) are described in the Help topic for the FileOpen command.

plugin_typecheck is optional, and informs DPlot whether a file is the correct format for plugin_readfile to interpret it.

__declspec(dllexport) int plugin_typecheck( char *Filename )

Return value should be:

This info is used for drag-and-drop operations, command line operations, opening a file with Explorer's "Open with..." right-click menu or double-clicking the filename if an association has been made with DPlot. If a file is not a DPlot file then DPlot checks with plugin_typecheck for all fileimport plugins for a match.

In all of the above cases (as opposed to opening a file with File>Open), if plugin_typecheck returns 1 then DPlot will, before calling plugin_readfile, write an entry to the registry indicating that default values should be used (at the discretion of the plugin). The key will be located at HKEY_CURRENT_USER\Software\DPlot\Plugins\FileImport\<plugin name> and have the value name 'UseDefaults'.

If the plugin checks for and responds to that setting, for example by using default options or the options used in the last call to plugin_readfile, then the plugin should also reset that entry before exiting:

if(RegCreateKeyEx(HKEY_CURRENT_USER,
"Software\\DPlot\\Plugins\\FileImport\\<plugin name>",
0,
NULL,
REG_OPTION_NON_VOLATILE,
KEY_ALL_ACCESS,
NULL,
&hKey,
&dwDisposition) == ERROR_SUCCESS)

{

         RegSetValueEx(hKey,"UseDefaults",0,REG_SZ,"0",1);
         RegCloseKey(hKey);

}

File Export functions

plugin_init is called by DPlot at startup.

__declspec(dllexport) int plugin_init( char *Desc,
                                      char *DefExt,
                                      int *DataType )

 

The return value of plugin_init should always be PLUGIN_INIT_OK.

plugin_version returns the version number of the DPLOT structure expected in subsequent calls to plugin_writefile. This function is required for structure versions 3 and later, and optional for earlier versions. See notes below.

__declspec(dllexport) int plugin_version()

plugin_writefile writes a data file.

__declspec(dllexport) int plugin_writefile( HWND hwndOwner,
                                          char Filename,
                                          DPLOT *DPlot,
                                          float *Data1,
                                          float *Data2)

plugin_writeimage writes a bitmap image of the currently active document window. Please note: This function is still supported but is obsolete and has been replaced with plugin_writeimage_ex (see below).

__declspec(dllexport) int plugin_writeimage( HWND hwndOwner,
                                            char Filename,
                                            HBITMAP hbmp,
                                            HPALETTE hpal)

__declspec(dllexport) int plugin_writeimage_ex( HWND hwndOwner,
                                              char Filename,
                                               HBITMAP hbmp,
                                               HPALETTE hpal,
                                              int *options)

Your plugin should include either plugin_writeimage or plugin_writeimage_ex, but not both. All parameters are as described above with the addition of:

Generate functions

plugin_init is called by DPlot at startup.

__declspec(dllexport) int plugin_init( char *Desc,
                                      char *Unused,
                                      int *Action )

PLUGIN_REPLACEDATA
Plugin operates on and replaces existing data in the same document.

PLUGIN_NEWDATA
Plugin operates on existing data and returns one or more data sets (curves) for the same document.

PLUGIN_NEWDOCUMENT
Plugin operates on existing data (or not) and returns an entirely new document. In this case the input provided by DPlot is a copy of an existing document – the plugin does not have to concern itself with opening a new window.

If combined with PLUGIN_DOUBLES, then the *X and *Y pointers passed to plugin_run will be for double- rather than single-precision arrays.

 

 

Return value for plugin_init should be PLUGIN_INIT_OK.

plugin_version returns the version number of the DPLOT structure expected in subsequent calls to plugin_run. This function is required for structure versions 3 and later, and optional for earlier versions. See notes below.

__declspec(dllexport) int plugin_version()

plugin_run modifies existing data or generates new data.

__declspec(dllexport) int plugin_run( HWND hwndOwner,
                                     DPLOT *DPlot,
                                    float *X, float *Y)

plugin_run_cmds is identical to plugin_run with the addition of an "Options" string in the argument list. A generate plugin should include either plugin_run or plugin_run_cmds, but not both. plugin_run requires DPlot version 2.3.2.1 or later.

__declspec(dllexport) int plugin_run_cmds( HWND hwndOwner,
                                     DPLOT *DPlot,
                                    float *X, float *Y,
                                    LPSTR Options)

For generate plugins distributed with DPlot, these options (when present) are described in the Help topic for Plugin modules.

DPLOT Structure

This defined type is used in calls to plugin_readfile, plugin_readfileex, plugin_writefile, and plugin_run. The DPLOT structure is defined in dplot.h, included with the example plugins and repeated here:

#define DPLOT_VERSION  4    // Version 4 of the DPLOT structure adds a 4th title line

                           //  and allows up to 200 characters for each title line

                           //  and axis label. It requires version 2.1 or later of

                           //  DPlot. Older structure versions are defined in dplot.h

#define MAXC 100            // Maximum number of curves in an XY plot. Do not change.

 

// These are the only data types supported by the plugin interface:

#define DATA_XYXY      0    // XY data

#define DATA_3D        3    // Z values on a rectangular grid

#define DATA_3DR       4    // Random X,Y,Z values

 

typedef struct tagDPLOT

{

   DWORD Version;          // version number of this structure

   DWORD hwnd;             // handle of client application window

                           // (Use DWORD rather than HWND)

   DWORD DataFormat;       // DATA_XYXY, DATA_3D, or DATA_3DR

   DWORD MaxCurves;        // maximum number of curves (must be <= 100)

                           // = NX for DataFormat = DATA_3D

                           //   ignore for DataFormat = DATA_3DR

   DWORD MaxPoints;        // maximum number of points/curve

                           // = NY for DataFormat = DATA_3D

                           // = 3 * number of points for DATA_3DR

   DWORD NumCurves;        // actual number of curves, always 1 for

                           //   DATA_3D or DATA_3DR

   DWORD Scale;            // scaling code (Linear, Log, etc.)

   float LegendX;          // left coord of legend, expressed as a ratio

                           //    of plot size (0->1)

   float LegendY;          // top coord of legend

   DWORD NP[MAXC];         // actual number of points in each curve;

                           //   cannot exceed MaxPoints.

                           // For DATA_3DR files, return number of nodes

                           //   in NP[0]

   DWORD LineType[MAXC];   // line types (see codes in dplot.h)

   DWORD SymbolType[MAXC]; // symbol types (see codes in dplot.h)

   LPSTR lpszCommands;     // Address of 32K character string that may

                           //   be used to pass command strings back to

                           //   DPlot.

                           //   NOTE: Requires DPlot version 2.0.7 or

                           //   later. Earlier versions of DPlot will

                           //   pass lpszCommands == NULL. Attempting to

                           //   use lpszCommands in this case will result

                           //   in a crash.

   char  Legend[MAXC+1][80];

                           // Legend[0] is the caption for the legend.

                           // Legend[n] is the legend for the n'th curve.

   char  Label[MAXC][40];  // Strings displayed beside the last data

                           //   point in a curve.

   char  Title[4][200];    // Four title lines.

   char  XAxis[200];       // X Axis label.

   char  YAxis[200];       // Y Axis label.

} DPLOT;

Plugin_readfile, plugin_readfileex, and plugin_run functions can pass DPlot command strings back to DPlot with the lpszCommands member. These commands are identical to those used in DPlot macros and/or in calls to the DPLOTLIB.DLL function DPlot_Command. For more information on DPlot command strings see Sending data to DPlot from another application.

NOTES

Plugins should be placed in the appropriate folder ("fileexport", “fileimport” or “generate”) below <dplot folder>\plugins.

Function plugin_version: Newer versions of the DPLOT structure reflect a few of DPlot’s newer capabilities, namely the ability to plot up to 100 curves (instead of 20) and use more characters in the legend, title lines, and axis labels. The change to the structure requires an additional function (plugin_version) to tell DPlot to send the address of the newer structure. Old plugins written for version 2 of the DPLOT structure will continue to work with newer versions of DPlot. New plugins using version 3 or 4 of the structure will not work with older versions of DPlot. If you write plugins for use by others, you will need to ensure that your users have version 1.8 or later of DPlot if you intend to use the version 3 structure, or version 2.1 or later of DPlot for the version 4 structure. You will also need to ensure that your plugin gracefully exits if the wrong structure version is passed (which will happen if the user has a version of DPlot older than 1.8). An example of this is included in the example plugins.

If you write a plugin you believe would be useful to others, let us know and it will be added to the DPlot download page.

Not a programmer? Registered users may request a new plugin to support additional file formats or data manipulation operations.

 

 

---

Page url: https://www.dplot.com/help/index.htm?helpid_plugin.htm