Programmer's Reference > Sending data to DPlot from another application

Macro commands may be used either in macros or by sending the commands to DPlot via dynamic data exchange (DDE). Some commands are valid only in macros (noted by Macros Only). Commands sent to DPlot via DDE must be enclosed by square brackets [ ]. Macro commands should not include the brackets.

Command parameters shown in the descriptions below are placeholders for the actual values. Command parameters are either numeric values, equations that evaluate to numbers, or character strings. Character string parameters are always bound by double quotation marks. Equations must be preceded by an equals sign (=).

The pipe symbol (|) in the command syntax indicates that a parameter is optional, and should not be included in your macro unless otherwise noted.

All indices into arrays are 1-based, e.g. Curve1=1 refers to the first curve in a plot.

A 0x prefix for numbers in the descriptions below indicates hexadecimal notation; e.g. 0x0010 = 16.

JR/Viewer indicates that the command is supported by DPlot Jr or DPlot Viewer.
JR/Viewer indicates that the command is NOT supported by DPlot Jr or DPlot Viewer.

[SetBackgroundImage("filename",full_image,force_extents,left,top,right,bottom,foreground,transparency,bkColor)]

JR Viewer

This command allows you to specify an image (BMP, GIF, JPG, PNG, or TIF) that will be drawn within the plot extents. The background image will be stretched to fill the plot exents, regardless of its width/height relative to the plot width/height.

If the "filename" argument does not include a path, DPlot will look for it in My Documents\DPlot\Images. If the image does not reside in that folder then "filename" should include the full path to the file. All other parameters are optional.

If you want to remove an existing background image, supply a blank "filename", e.g. [SetBackgroundImage("")]. All other arguments are optional.

full_image

Default value is 1 (entire image will be used). If set to 0 then the left, top, right, and bottom values specify the top-down extents within the image that you want to use as a background. left, top, right, and bottom are ignored for a non-zero full_image value.

force_extents

Default value is 1. If non-zero then the plot extents will be adjusted such that the background has a 1:1 pixel ratio. For example if the background image is 800 x 600 pixels and this box is checked, then the width and height of the plot will be set to a 4:3 ratio. If "Specify plot size" was previously selected then the maximum dimension will be used for the larger of the width/height. If "Specify plot size" has not been previously selected then the maximum dimension will be set to 8 inches. This adjustment takes place at the time this command is issued and is not persistent: Subsequently changing the plot size with a Size command or with the Extents/Intervals/Size menu command may result in a distorted background image.

foreground

If non-zero, the image will be drawn after all other objects. Default=0 (image is drawn before all objects).

transparency

Global transparency value applied to entire image. Valid range is 0 (invisible) to 255 (opaque). Default value = 255 (opaque).

bkColor

Color that will not be drawn, in the form (blue*65536)+(green*256)+red, where blue, green, and red range from 0 to 255. The color value may be expressed as a decimal or hexadecimal value; hexadecimal notation should include a "0x" prefix. For example 0x00FF00FF and 16711935 both represent magenta (blue=red=255, green=0). This value will be ignored for 32-bit images with an alpha channel. If bkColor is set to a negative value, no color will be removed from the image.

Background images are only applicable to 2D views of your data, and are not used for polar plots or triangle plots.

Please note:

Character string arguments require a bit of care, depending on your development environment. Character string arguments in all DPlot commands are always enclosed by double quotation marks. In some environments (Visual Basic and all flavors of C, for example), double quotation marks are also used to delineate all character strings (including the command itself). The following example will always cause a syntax error in Visual Basic:

ret = DPlot_Command(docnum,"[FileOpen("myfile.grf")]")

Instead, use:

ret = DPlot_Command(docnum,"[FileOpen(""myfile.grf"")]")

in C, C++, C# you'd accomplish the same thing with:

ret = DPlot_Command(docnum,"[FileOpen(\"myfile.grf\")]");

If a character string argument is a variable, as in (VB):

Dim arg as string
arg = "myfile.grf"

... then you can build the command in VB as:

ret = DPlot_Command(docnum,"[FileOpen(" & chr$(34) & arg & chr$(34) & ")]")

In all flavors of C, the same can be accomplished with

char arg[256];
char cmd[512];
strcpy(arg,"myfile.grf");
sprintf(cmd,"[FileOpen(\"%s\")]",arg);
ret = DPlot_Command(docnum,cmd);

This does not apply to the DPlot macro editor, in which each line is by definition a character string and does not require delineators, nor to FORTRAN and possibly other languages, in which the delineator for character strings is a single quote, e.g. '[FileOpen("...")]'

To embed a double quotation mark within a character string which is itself delineated by double quotation marks, use the Symbol font equivalent instead. For example, "Radius=6{\s²}" inches will be processed as

Radius=6"

____________________________