Parameters
DocNum
|
Document index returned by a previous call to DPlot_Plot (1-32) or 0 to request system information from DPlot (see Remarks).
|
item
|
Item that you want to request the value of. Must be null-terminated.
|
value
|
Address of buffer for text. Returned text will be null-terminated.
|
maxcount
|
Specifies the maximum number of characters to copy to value, including the NULL character. If the text exceeds this limit, value is undefined and an error code is returned.
|
Return Values
>0
|
Success. Size, in bytes, of the value character string, not including the terminating null character.
|
0
|
Generic error attempting to communicate with DPlot. This most often indicates that DPlot is currently busy, e.g. a modal dialog box is open.
|
-2
|
Could not establish a DDE connection with DPlot. Either DPlot is not open (user might have closed it) or you requested information from a document that does not exist (which might happen, for example, if the user closes the document window).
|
-3
|
Length of the requested information is larger than maxcount. In this case the required length is returned in maxcount.
|
-4
|
Unrecognized item.
|
Remarks
For a full description of the information that can be retrieved from DPlot, see the Transferring DPlot data to other applications section of DPlot's Help file. The most common uses for DPlot_Request are shown here:
For DocNum=0, valid items and typical return values are:
item
|
Description
|
Status
|
"Ready" or "Busy". This gives an indication of whether DPlot may currently accept commands from DPLOTLIB or other DDE sources.
|
ActiveDocument
|
Index of the currently active document window (1-32). Note that this window might have been activated either by DPLOTLIB.DLL or the user.
|
DecimalSymbol
|
Character used for the decimal symbol in numbers. This symbol is used by DPlot when interpreting text files or columns of numbers from the Clipboard and for entries in text boxes. It is not used when saving text files, copying data to the clipboard, or in macro commands.
|
NumberOfDocuments
|
Current number of open document windows. These windows do not necessarily contain a plot.
|
NumUsedDocuments
|
Number of document windows containing a plot. This information is used, for example, by DPlot_Stop to determine whether DPlot should be shut down.
|
LastNewCaption
|
Returns the caption of the last document created.
|
LastNewDocNum
|
Returns the document index (1-32) of the last document created.
|
For DocNum > 0:
item
|
Description
|
DocumentType
|
Returns the data type for the referenced document. 0=XY plot, 3=3D surface plot, points on a rectangular grid, 4=3D surface plot, randomly-spaced points, 6=1D box-and-whisker plot or dot graph, 7=3D scatter plot, 8=4D surface plot, 9=4D scatter plot.
|
Legend(n)
|
Legend title for n=0, or legend entry for curve n, n=1 through number of curves.
|
ListPeaks
|
Output is identical to that of the List Peak Values menu command for XY plots. Not valid for 1D and 3D plots.
|
MaxCurves
|
Allocated number of curves or data sets for the current plot. Meaningless for 3D surface plots.
|
MaxPoints
|
Allocated number of points per curve or data set for the current plot. Meaningless for 3D surface plots.
|
NumberOfCurves
|
Number of curves in the current XY plot or number of groups in the current 1D plot. Always returns 1 for 3D plots.
|
NumberOfPoints
|
Tab-separated list of the number of points in each curve, surface, or 1D group.
|
PlotMetrics
|
Returns scaling information for the plot: XlowDisplay, YlowDisplay, XhighDisplay, YhighDisplay, XlowData, YlowData, XhighData, YhighData, where:
XlowDisplay =
|
|
Horizontal 0-based pixel index of the left side of the plot.
|
YlowDisplay =
|
|
Vertical 0-based pixel index of the bottom side of the plot (0=top of display).
|
XhighDisplay =
|
|
Horizontal 0-based pixel index of the right side of the plot.
|
YhighDisplay =
|
|
Vertical 0-based pixel index of the top of the plot.
|
XlowData =
|
|
Left side of the plot in X units (data space).
|
YlowData =
|
|
Bottom side of the plot in Y units.
|
XhighData =
|
|
Right side of the plot in X units.
|
YhighData =
|
|
Top side of the plot in Y units.
|
|
PlotMetricsEx
|
Same as PlotMetrics, with additional parameters that have meaning only for 3D plots: XlowDisplay, YlowDisplay, XhighDisplay, YhighDisplay, XlowData, YlowData, XhighData, YhighData, XScale, YScale, ZScale, Scale, Azimuth, Elevation, where:
XScale =
|
|
X Scale factor (set with [ContourScales()] or on Contour Options dialog.
|
YScale =
|
|
Y Scale factor
|
ZScale =
|
|
Z Scale factor
|
Scale =
|
|
Scale factor used to transform horizontal and vertical projections to pixel coordinates.
|
Azimuth =
|
|
View angle around the Z axis, radians.
|
Elevation =
|
|
Elevation angle of the view point, radians.
|
|
Titlen (n=1-4)
|
The n'th title line
|
XAxisLabel
|
X axis title
|
YAxisLabel
|
Y axis title
|
ZAxisLabel
|
Z axis title
|
ZFromXY
|
For 3D plots, returns the interpolated Z value for the X,Y coordinates set with a call to DPlot_Command with the [SetXY()] command.
|
|
