The XyPlot object draws curves made up of X/Y coordinate pairs with tick marks, titles, and a legend.
Header file: ncarg/hlu/XyPlot.h Class name: xyPlotClass Class pointer: NhlxyPlotClass Fortran class function: NHLFXYPLOTCLASS Superclass: DataComm Composite classes: PlotManager,LogLinTransformation,IrregularTransformation Data specific class Class name: xyDataSpecClass Class pointer: <Not referenceable> Fortran class function: <Not referenceable> Superclass: DataSpec
Type name: NhlTAlternatePlace Definition: typedef enum _NhlAlternatePlace{ NhlNONE = 0, /* "none" */ NhlLEFTAXIS = 1, /* "leftAxis" */ NhlRIGHTAXIS = 2, /* "rightAxis" */ NhlTOPAXIS = 3, /* "topAxis" */ NhlBOTTOMAXIS = 4 /* "bottomAxis" */ } NhlAlternatePlace; Type name: NhlTLineLabelMode Definition: typedef enum _NhlLineLabelMode{ NhlNOLABELS = 0, /* "noLabels" */ NhlLETTERED = 1, /* "lettered" */ NhlCUSTOM = 2 /* "custom" */ } NhlLineLabelMode;
+---------------------------------------------------------------+ | XyPlot resource set | |---------------------------------------------------------------| | NAME TYPE ACCESS | | CLASS DEFAULT | |===============================================================| | xyCoordData NhlTObjIdGenArray CSG | | XyCoordData NULL | |---------------------------------------------------------------| | xyCoordDataSpec NhlTObjIdGenArray G | | XyCoordDataSpec NULL | |---------------------------------------------------------------| | xyCurveDrawOrder NhlTDrawOrder RCSG | | XyCurveDrawOrder "Draw" | |---------------------------------------------------------------| | xyXStyle NhlTTickMarkStyle RCSG | | XyXStyle NhlLINEAR | |---------------------------------------------------------------| | xyYStyle NhlTTickMarkStyle RCSG | | XyYStyle NhlLINEAR | |---------------------------------------------------------------| | xyXIrregularPoints NhlTFloatGenArray RCSG | | XyXIrregularPoints NULL | |---------------------------------------------------------------| | xyYIrregularPoints NhlTFloatGenArray RCSG | | XyYIrregularPoints NULL | |---------------------------------------------------------------| | xyXIrrTensionF NhlTFloat RCSG | | XyXIrrTensionF 2.0 | |---------------------------------------------------------------| | xyYIrrTensionF NhlTFloat RCSG | | XyYIrrTensionF 2.0 | |---------------------------------------------------------------| | xyComputeXMin NhlTBoolean RCSG | | XyComputeExtent <dynamic> | |---------------------------------------------------------------| | xyComputeXMax NhlTBoolean RCSG | | XyComputeExtent <dynamic> | |---------------------------------------------------------------| | xyComputeYMin NhlTBoolean RCSG | | XyComputeExtent <dynamic> | |---------------------------------------------------------------| | xyComputeYMax NhlTBoolean RCSG | | XyComputeExtent <dynamic> | +---------------------------------------------------------------+
The following resources are not set directly to the XyPlot object. These resources are used to set the graphical attributes that correspond directly with an individual piece of data that is added to the plot. So the attributes of each individual curve or marker are set this way.
When a DataItem object is added to the xyCoordData resource, either using NhlAddData or using NhlSetValues, an XyDataSpec object is automatically created as a child of the XyPlot to hold the resources that describe these graphical attributes. The XyDataSpec object is given the same name as the DataItem object that was added.
To set these resources in a resource file, you would use resource lines similar to this:
*xyplotname.dataspecname.xyDashPattern: solidline
To set these resources programmatically, you need to retrieve the XyDataSpec object id, and call NhlSetValues on that object.
There are two ways to retrieve the ids for the XyDataSpec objects that hold the resources that describe the graphical attributes for a particular DataItem:
The XyDataSpec class also inherits all the DataSpec resources.
+---------------------------------------------------------------+ | XyDataSpec resource set | |---------------------------------------------------------------| | NAME TYPE ACCESS | | CLASS DEFAULT | |===============================================================| | xyDashPattern NhlTDashIndex RSG | | LineDashPattern NhlSOLIDLINE | |---------------------------------------------------------------| | xyDashPatterns NhlTDashIndexGenArray RSG | | XyDashPatterns NULL | |---------------------------------------------------------------| | xyMonoDashPattern NhlTBoolean RSG | | XyMonoDashPattern False | |---------------------------------------------------------------| | xyMarkLineMode NhlTMarkLineMode RSG | | XyMarkLineMode NhlLINES | |---------------------------------------------------------------| | xyMarkLineModes NhlTMarkLineModeGenArrayRSG | | XyMarkLineModes NULL | |---------------------------------------------------------------| | xyMonoMarkLineMode NhlTBoolean RSG | | XyMonoMarkLineMode False | |---------------------------------------------------------------| | xyExplicitLegendLabels NhlTStringGenArray RSG | | XyExplicitLegendLabels NULL | |---------------------------------------------------------------| | xyLineColor NhlTColorIndex RSG | | LineColor NhlFOREGROUND | |---------------------------------------------------------------| | xyLineColors NhlTColorIndexGenArray RSG | | XyLineColors NULL | |---------------------------------------------------------------| | xyMonoLineColor NhlTBoolean RSG | | XyMonoLineColor False | |---------------------------------------------------------------| | xyLineDashSegLenF NhlTFloat RCSG | | LineDashSegLenF <Dynamic> | |---------------------------------------------------------------| | xyLineLabelFontHeightF NhlTFloat RCSG | | FontHeightF <Dynamic> | |---------------------------------------------------------------| | xyLineLabelFontColor NhlTColorIndex RSG | | FontColor NhlFOREGROUND | |---------------------------------------------------------------| | xyLineLabelFontColors NhlTColorIndexGenArray RSG | | XyLineLabelFontColors NULL | |---------------------------------------------------------------| | xyMonoLineLabelFontColor NhlTBoolean RSG | | XyMonoLineLabelFontColor False | |---------------------------------------------------------------| | xyLabelMode NhlTLineLabelMode RSG | | XyLabelMode NhlNOLABELS | |---------------------------------------------------------------| | xyExplicitLabels NhlTStringGenArray RSG | | XyExplicitLabels NULL | |---------------------------------------------------------------| | xyLineThicknessF NhlTFloat RSG | | LineThicknessF 1.0 | |---------------------------------------------------------------| | xyLineThicknesses NhlTFloatGenArray RSG | | XyLineThicknesses NULL | |---------------------------------------------------------------| | xyMonoLineThickness NhlTBoolean RSG | | XyMonoLineThickness False | |---------------------------------------------------------------| | xyMarker NhlTMarkerIndex RSG | | MarkerIndex "default" | |---------------------------------------------------------------| | xyMarkers NhlTMarkerIndexGenArray RSG | | XyMarkers NULL | |---------------------------------------------------------------| | xyMonoMarker NhlTBoolean RSG | | XyMonoMarker False | |---------------------------------------------------------------| | xyMarkerColor NhlTColorIndex RSG | | MarkerColor NhlFOREGROUND | |---------------------------------------------------------------| | xyMarkerColors NhlTColorIndexGenArray RSG | | XyMarkerColors NULL | |---------------------------------------------------------------| | xyMonoMarkerColor NhlTBoolean RSG | | XyMonoMarkerColor False | |---------------------------------------------------------------| | xyMarkerSizeF NhlTFloat RSG | | MarkerSizeF 0.01 | |---------------------------------------------------------------| | xyMarkerSizes NhlTFloatGenArray RSG | | XyMarkerSizes NULL | |---------------------------------------------------------------| | xyMonoMarkerSize NhlTBoolean RSG | | XyMonoMarkerSize False | |---------------------------------------------------------------| | xyMarkerThicknessF NhlTFloat RSG | | MarkerThicknessF 1.0 | |---------------------------------------------------------------| | xyMarkerThicknesses NhlTFloatGenArray RSG | | XyMarkerThicknesses NULL | |---------------------------------------------------------------| | xyMonoMarkerThickness NhlTBoolean RSG | | XyMonoMarkerThickness False | |---------------------------------------------------------------| | xyLineLabelFont NhlTFont RCSG | | Font "pwritx" | |---------------------------------------------------------------| | xyLineLabelFontAspectF NhlTFloat RCSG | | FontAspectF 1.3125 | |---------------------------------------------------------------| | xyLineLabelFontThicknessF NhlTFloat RCSG | | FontThicknessF 1.0 | |---------------------------------------------------------------| | xyLineLabelFontQuality NhlTFontQuality RCSG | | FontQuality "High" | |---------------------------------------------------------------| | xyLineLabelConstantSpacingF NhlTFloat RCSG | | TextConstantSpacingF 0.0 | |---------------------------------------------------------------| | xyLineLabelFuncCode NhlTCharacter RCSG | | TextFuncCode ':' | +---------------------------------------------------------------+
All Transformation superclass resources are accessible. However, XyPlot blocks access to all resources specific to the LogLinTransformation.
All Transformation superclass resources are accessible. However, XyPlot blocks access to all resources specific to the IrregularTransformation except for:
Conditional
.
Conditional
.
Never
.
NoCreate
in the XyPlot.
Since the XyPlot is a composite object, the resources for the Composite classes are also available to the XyPlot object through the standard resource-setting mechanisms.
XyPlot is derived from the DataComm class, which is derived from the Transform class. This means that the functions NhlDataToNDC and NhlNDCToData can be used to obtain transformations of points to and from data coordinates and NDC coordinates. See the Transform class for more information on these functions.
In general, XyPlot accepts one or more vectors of X and Y coordinates and displays them by drawing a line through the {X,Y} coordinate pairs, or drawing markers at each point within the coordinate pairs, or both.
XyPlot provides the user with the capability of configuring the line thickness, dash pattern indexes, colors of the lines, line labels, and line label colors for curves. XyPlot allows the user to configure Marker indexes, colors, sizes, and thicknesses for displaying markers. XyPlot also provides all the same transformation styles that are provided by the TickMark object: LOG, LINEAR, and IRREGULAR.
XyPlot accepts DataItem objects rather than arrays of values. The xyCoordData resource is used to associate DataItem objects with the XyPlot object. The xyCoordData resource is used to specify a list of DataItem objects, and the AddData function appends DataItems to the list.
There are basically two steps to visualizing a set of data in the XyPlot object. First, the programmer has to fully describe the data to the HLU environment. This is done by creating a DataItem object that describes the data's shape. Second, the programmer has to associate the DataItem with the xyCoordData resource of the XyPlot.
You can associate data with XyPlot by creating a DataItem to describe the data. Then use the NhlAddData function to add that DataItem to the list of data referenced by the xyCoordData resource. If the XyPlot object understands data in the format provided (i.e. the DataItem class used), the NhlAddData function will return with a value of NhlNOERROR.
Additionally, the programmer can just set the xyCoordData resource directly using the NhlSetValues function. The xyCoordData resource is set with an array of object ids. The difference between setting the resource directly and calling the NhlAddData function is that the NhlAddData function appends the given data to the current list of data, while setting the xyCoordData resource using NhlSetValues replaces the current value of that resource.
If programmers want to control the XyDataSpec resources programmatically, they will need to add the DataItems to the XyPlot's xyCoordData resource first. Then they can retrieve the value of the xyCoordDataSpec resource. The xyCoordDataSpec resource is an array of XyDataSpec ids. The elements of this array correspond to the DataItem ids in the xyCoordData array resource. To configure exactly how each coordinate pair array of one of the DataItems is going to be displayed, the programmer can set the XyDataSpec resources to the corresponding XyDataSpec id.
The XyDataSpec object is created on behalf of the programmer for each DataItem object that is added to the xyCoordData resource. The XyDataSpec object is created with the same name as the DataItem and as a child of the XyPlot. Therefore, the data-specific resources (i.e. the resources of the XyDataSpec object) can be set in the resource file by simply specifying the name of the DataItem as a child of the XyPlot with the XyDataSpec resources in the resource file.
The XyDataSpec resources allow the user to set dash patterns, line colors, line thicknesses, line labels, and line label font colors and heights for each element of the xyCoordData resource. The user can also set the other standard text attributes for line labels. However, these attributes are only available as scalar resources, and therefore the XyDataSpec object referenced by the first element of the xyCoordDataSpec array supplies the values of these resources for all data elements.
The xyLabelMode and xyExplicitLabels resources control how each curve is labeled. The curve line labels can be any string. However, line labels longer than six or seven characters can cause problems, and spaces are not drawn.
XyPlot also allows markers to be plotted. The xyMarkLineMode, xyMarkLineModes, and xyMonoMarkLineMode resources are used to indicate if markers should be plotted in place of curves, or in addition to them. There are also a number of other resources in the XyDataSpec object to configure exactly how the markers should be displayed.
The next step in configuring an XyPlot is to select and
specify the data transformation of the XyPlot object. As is
the case with the TickMark object, there are currently three
styles of data transformations, Log
, Linear
,
and Irregular
. There are two
style resources for setting the X-Axis and Y-Axis data transformations.
This differs from the TickMark object, where each side of
each axis has its own resource for specifying style.
XyPlot forces both sides of an axis to have the same
style, so there is no need for two separate style resources that set the style
for each side of an axis. This has been done to eliminate the possibility
that the tick marks don't accurately represent the data transformation.
If different styles were allowed for both sides of the X Axis, then the
possibility arises that one of the transformations is wrong. The two resources
for selecting the transformation style are xyXStyle and
xyYStyle. By default, these are both set to Linear
.
Once the style is selected, the resources trXMinF, trXMaxF, trYMinF, and trYMaxF are used to set the data extents. If these resources are not set, then the XyPlot object examines the data and determines for itself what the data extents are. The actual data extents could change if additional data are added to the xyCoordData resource or if one of the current DataItems is modified. The tr data-extent resources will be automatically recomputed if the xyComputeXMin, xyComputeXMax, xyComputeYMin, and xyComputeYMax resources allow it.
Irregular
style transformations require some additional
information. The resources xyXIrregularPoints and
xyYIrregularPoints must be used when Irregular
style has been selected. These resources apply to both sides of their
respective axes. For a more complete discussion of Irregular
style transformations, see the description of the
TickMark object.
NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?