Description: This statement displays a plot of a curve in the window given the X and Y values in two arrays.
Returns: Nothing
Usage: Steady State
Format: PlotXY(XArrayElem, YArrayElem, N, LowX, HighX, LowY, HighY, X1, Y1, X2, Y2, Style, Color)
< OR >
PlotXY(XArrayElem, YArrayElem, N, LowX, HighX, LowY, HighY, X1, Y1, X2, Y2, Pen, Reserved [, XORMode, Direction, DrawStepped, BitNumber, Average])
Note: PlotXY takes the first parameter set or else senses that the Style parameter is a Pen, in which cast the second parameter set is used:
Parameters: XArrayElem { array element } { required } { no default: }
Any array element giving the starting point in the array of X coordinates. The subscript for the array may be any numeric expression. Unless specified, the lowest dimension of a multidimensional array is used.
YArrayElem { array element } { required } { no default: }
Any array element giving the starting point in the array of Y coordinates. The subscript for the array may be any numeric expression. Unless specified, the lowest dimension of a multidimensional array is used.
N { numeric } { required } { no default: }
Any numeric expression giving the number of array elements to plot starting at the element given by the first parameters. N must be greater than or equal to 0, and no greater than 16384. If this parameter is greater than the dimension of the first array, the number of points plotted will be that array dimension. If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
LowX { numeric } { required } { no default: }
Any numeric expression that defines the limit of data values to be plotted. This value need not be less than HighX but must not be equal to it. In the standard case, when this value is less than HighX, it will define the minimum value to be displayed from the array of X-values. For example, if LowX was 10, a data value of 10 would fall on the edge of the bounding box, on either X1, if the plot is vertical, or on Y1, if the plot is horizontal. Any values below 10 in this case would not be shown - they would be outside the clipped box.
HighX { numeric } { required } { no default: }
Any numeric expression that defines the limit of data values to be plotted. This value need not be greater than LowX but must not be equal to it. In the standard case, when this value is greater than LowX, it will define the maximum value to be displayed from the array of X-values. For example, if HighX was 1000, a data value of 1000 would fall on the edge of the bounding box, on either X2, if the plot is vertical, or on Y2, if the plot is horizontal. Any values above 1000 in this case would not be shown - they would be outside the clipped box.
LowY { numeric } { required } { no default: }
Any numeric expression that defines the limit of data values to be plotted. This value need not be less than HighY but must not be equal to it. In the standard case, when this value is less than HighY, it will define the minimum value to be displayed from the array of Y-values. For example, if LowY was 10, a data value of 10 would fall on the edge of the bounding box, on either Y1, if the plot is vertical, or on X1, if the plot is horizontal. Any values below 10 in this case would not be shown - they would be outside the clipped box.
HighY { numeric } { required } { no default: }
Any numeric expression that defines the limit of data values to be plotted. This value need not be greater than LowY but must not be equal to it. In the standard case, when this value is greater than LowY, it will define the maximum value to be displayed from the array of Y-values. For example, if HighY was 1000, a data value of 1000 would fall on the edge of the bounding box, on either Y2, if the plot is vertical, or on X2, if the plot is horizontal. Any values above 1000 in this case would not be shown - they would be outside the clipped box.
X1 { numeric } { required } { no default: }
Any numeric expression giving the X coordinate on the screen of one side of the plot area. This is typically, although not necessarily, the left side of the plot. This corresponds to the LowX parameter for horizontal plots and to the LowY parameter for vertical plots.
Y1 { numeric } { required } { no default: }
Any numeric expression giving the Y coordinate on the screen of one side of the plot area. This is typically, although not necessarily, the top of the plot. This corresponds to the LowY parameter for horizontal plots and to the LowX parameter for vertical plots.
X2 { numeric } { required } { no default: }
Any numeric expression giving the X coordinate on the screen of the side of the plot area opposite to X1. This is typically, although not necessarily, the right side of the plot. This corresponds to the HighX parameter for horizontal plots and to the HighY parameter for vertical plots.
Y2 { numeric } { required } { no default: }
Any numeric expression giving the Y coordinate on the screen of the side of the plot area opposite to Y1. This is typically, although not necessarily, the bottom of the plot. This corresponds to the HighY parameter for horizontal plots and to the HighX parameter for vertical plots.
Style { numeric } { required } { no default: }
Any numeric expression giving the style of the plot - the line style, direction, bit number for bits plots, and the number of points to average per point displayed. If PlotXY senses that the Style parameter is a Pen, XORMode, DrawStepped, BitNumber, and Average parameters (see below) will become relevant. The Style is determined by adding together the following values.
Line style + Direction + Path + Bit number + Average
Line style is a number between 1 and 10 inclusive which gives the line style for line plots. A line style of 1 indicates a solid line. For other line styles, the background color is set to the current background screen color.
Direction is either 0 or 10. A 0 indicates a horizontal plot and a 10 indicates a vertical plot.
Path is either 0 or 50. A 0 indicates that line plots are to be drawn directly from point to point. A 50 indicates that plots are to be drawn in a step fashion with two line segments between each point. The first segment runs parallel to the X-axis and the second segment runs parallel to the Y-axis. This produces a square-looking plot. These step plots are useful for plotting status values which change in jumps rather than continuously.
Bit number is the number of the bit to use in the YArray data for plotting. If the normal entire value of the data is to be plotted, use 0 for this value. If only one of the bits from the data is to be plotted, use the bit number plus 1. The value to add is (Bit number + 1) * 100 or 0. The ability to plot only a single bit from an array of short or long values allows status data to be stored very efficiently by not requiring a separate array for each status value. For bit plots, the value plotted is always a 0 or a 1 corresponding to the value of the selected bit. The use of this plotting option is usually done in conjunction with a Path value of 50 for step plots.
Average is the number of consecutive array points to average to give a single point on the screen. Both XArray and YArray values are averaged. It can be used to plot a very large array of values on the screen without having to draw all of the points on the screen. This will produce a smoothed plot and reduce the drawing time. The number to add is (Data points per displayed point + 1) * 10000.
Color is any numeric expression giving the color of the line and the foreground color for filled plots. If the number is less than 10000, the plot is non-destructive. If the number is greater than or equal to 10000, the plot is destructive and the actual color used is Color - 10000.
Pen is the pen to be used (if any).
Reserved has been allocated to permit the addition of a Brush parameter, should such a parameter become necessary in the future. Reserved can currently be any value or Invalid.
XORMode { numeric } { optional } { no default: }
An optional parameter specifying whether or not the plot is destructive (if destructive, the plot line won't be affected by the background color). If set to 0 or Invalid (default), the destructive drawing mode will be employed. If set to 1, the non-destructive or XOR drawing mode will be employed.
Direction { numeric } { optional } { no default: }
An optional parameter specifying the horizontal or vertical direction for the plot. 0 or Invalid indicates horizontal, while 1 indicates vertical.
DrawStepped { numeric } { optional } { no default: }
An optional parameter specifying whether the plot is to be drawn from point-to-point, or stepped. 0 or Invalid indicates point-to-point, while 1 indicates stepped.
BitNumber { numeric } { optional } { no default: }
An optional parameter specifying the use of a whole value or a bit number. Invalid indicates a whole value should be used, while >=0 indicates that the specified bit number should be used.
Average { numeric } { optional } { no default: }
An optional parameter specifying whether or not consecutive points should be averaged to give a single point. Invalid or 0 indicates that averaging should not be employed, while >0 indicates that the number of consecutive points should be averaged to give a single point.
Comments: This function is a layered graphics statement.
The PlotXY statement will execute timer functions during the plotting process. This will allow time critical functions such as driver I/O and data logging to continue running during the relatively long times it takes to update a plot on the screen.
Through the ordering of the LowX, HighX, LowY, HighY, X1, X2, Y1, and Y2 parameters, the plot may have 8 different orientations. The normal left to right orientation with the minimum at the bottom will have LowX < HighY, LowY < HighY, X1 < X2, and Y1 > Y2.
Exchanging either LowX and HighX (i.e. LowX > HighX) or X1 and X2 (i.e. X1 > X2), the plot will be from right to left. This means that the minimum X-value will be on the right rather than the left. Exchanging either LowY and HighY (i.e. LowY > HighY) or Y1 and Y2 (i.e. Y1 > Y2),will result in the plot will having its minimum Y-value at the top rather than the bottom.
PlotXY ignores invalid data elements in the arrays and leaves blank spaces for them on the display. If the X-values are not in order, the plot will appear as a scatter of lines. The Sort statement may be used to order the points in the arrays prior to plotting.
The plot area defined by X1, Y1, X2, and Y2 limits the area which can be plotted on the screen. Any points which fall outside this area will not appear on the screen but will be "clipped" at the boundary.
Example:
Two arrays called speed and efficiency exist that each have 100 elements. The array called speed has values that range from 0 to 1800, while efficiency has values ranging from 0 to 100 (percent). A plot of speed against efficiency may be done with the following:
PlotXY(speed[0] { Starting element of X-values },
efficiency[0] { Starting element of Y-values },
100 { Number of elements to plot },
0, 1800 { Low/high limits for speed },
0, 100 { Low/high limits for efficiency },
0, 500, 500, 0 { Bounding box for clipped area },
1 { Solid line style, horizontal plot },
15 { Plot is white });
This statement will result in a line plot of 100 data points in an area in the upper left corner of the window. The line will be horizontally orientated, solid in style and white in color.
See Also: