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.
|
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.
|
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.
|
|
