# Programming with Graph Controls

Use graph controls to display graphical data as one or more plots. The following topic describes how to program with graph controls.

## Plots

Graph controls can contain a variety of different plot types, each representing different types of data. You can use plotting functions to plot different types of data.

The plotting functions behave like SetCtrlVal in that if the graph is visible, drawing takes place immediately, without the need to process events.

When you plot data on a graph, you receive a plot handle, which you can use in later functions calls to refer to an individual plot.

DeleteGraphPlot removes the specified plot from a graph. If you set the plotHandle parameter to -1, DeleteGraphPlot deletes all plots on a graph.

You can customize individual plots by setting attributes on a given plot handle using SetPlotAttribute and GetPlotAttribute.

To view plots on the legend control, use the following function:

SetCtrlAttribute (panelHandle, controlID, ATTR_LEGEND_VISIBLE, 1);

## Cursors

You can configure a graph control to contain a given number of cursors, using SetCtrlAttribute with the ATTR_NUM_CURSORS attribute. You can use the following functions to manipulate graph cursors: GetGraphCursor, SetGraphCursor, GetGraphCursorIndex, SetGraphCursorIndex, GetActiveGraphCursor, SetActiveGraphCursor, GetCursorAttribute, and SetCursorAttribute. Refer to cursors through their one-based index.

| Note You cannot remove a specified cursor. For example, when you change the value of ATTR_NUM_CURSORS from 5 to 3, the graph control eliminates the last two cursors.

## Annotations

You can use graph annotations to mark specific data points on a graph. Call AddGraphAnnotation to add a new annotation to a graph. Identify each annotation through its one-based index, which you can obtain by calling GetAnnotationIndexFromCaption. You can customize individual annotations using annotation attributes, which you can get and set by calling GetAnnotationAttribute and SetAnnotationAttribute. You can delete a specific annotation or all annotations from a graph using DeleteGraphAnnotation.

## Axes

A graph always contains two x-axes and y-axes. By default, only the bottom x-axis and left y-axis are visible.

The following code makes the top x-axis visible:

SetCtrlAttribute (panelHandle, controlID, ATTR_ACTIVE_XAXIS, VAL_TOP_XAXIS);
SetCtrlAttribute (panelHandle, controlID, ATTR_XLABEL_VISIBLE, 1);

The following code makes the right y-axis visible:

SetCtrlAttribute (panelHandle, controlID, ATTR_ACTIVE_YAXIS, VAL_RIGHT_AXIS);
SetCtrlAttribute (panelHandle, controlID, ATTR_YLABEL_VISIBLE, 1);

You can choose to make one, both, or neither of the axes visible.

The ATTR_ACTIVE_XAXIS and ATTR_ACTIVE_YAXIS attributes determine which of the two axes are used for the following actions:

- Adding a plot to the graph. The active axis serves as the scaling reference.
- Setting an axis attribute. Each axis has its own attribute values.
- Setting the axis range.
- Creating a graph cursor. The cursor is associated with the active axis.

After you add a plot to a graph, you can associate it with the other axis using SetPlotAttribute with the ATTR_PLOT_XAXIS or ATTR_PLOT_YAXIS attributes.

After you create a graph cursor, you can associate it with the other axis using SetCursorAttribute with the ATTR_CURSOR_XAXIS or ATTR_CURSOR_YAXIS attributes. The associated axis serves as the reference for the cursor position coordinates in calls to SetGraphCursor and GetGraphCursor.

You can use all ATTR_XY... attributes to set values for each x and y-axis.

GetAxisScalingMode obtains the current scaling mode and range of one of the axes of a graph control.

SetAxisScalingMode sets the current scaling mode and range of one of the axes of a graph control.

## Axis Strings

You can replace the numeric labels of graph axes with custom text strings. When you enable the ATTR_XUSE_LABEL_STRINGS or ATTR_YUSE_LABEL_STRINGS attribute, the graph displays text strings at given axis locations, instead of the default numeric labels. Specify these strings in the form of label/value pairs, which you create in the Edit Graph dialog box or programmatically using InsertAxisItem. You can use multi-line text strings for graph axes.

You can use functions such as GetAxisItem, ReplaceAxisItem, and DeleteAxisItem to manipulate these label/value pairs.

Each individual string displays only when the value it is associated with falls within the range of the axis.

## Specifying Dates and Times for Axis Values

Use the ATTR_XFORMAT and ATTR_YFORMAT attributes to specify the display format of the x-axis and y-axis values. To display date/time data, set the display format to VAL_RELATIVE_TIME_FORMAT or VAL_ABSOLUTE_TIME_FORMAT.

If you use the absolute time format, LabWindows/CVI expects that you plot data that contains the number of seconds since January 1, 1900. This format is compatible with the format the time and GetCurrentDateTime functions use. If you use the relative time format, LabWindows/CVI expects that you plot data that contains the number of seconds since some arbitrary point in time, commonly denoted as t0. For example, you might use the start of a data acquisition process as the arbitrary point in time.

You can call SetAxisTimeFormat to change the format string that specifies how the date/time is displayed on the specified axis. The format string can contain the specifiers that the ANSI C strftime function supports. You also can use an additional specifier, %nf, which represents the fractional part of the seconds, and the @ modifier, which restricts overflow for certain time units.

When the axes are in absolute time or relative time format, the value you specify for ATTR_XAXIS_OFFSET or ATTR_YAXIS_OFFSET is the t0 value. The value you specify for ATTR_XAXIS_GAIN or ATTR_YAXIS_GAIN is the Δt value. Call MakeDateTime or GetCurrentDateTime to obtain time values you can use as ATTR_XAXIS_OFFSET and ATTR_YAXIS_OFFSET values. You also can pass time values to the SetAxisScalingMode min and max parameters when you configure an axis for manual scaling.

## Performance

This section presents attributes related to graphing and discusses how various settings affect performance.

### Optimizing Speed

The following attributes affect the speed and appearance of the graph updates.

Smooth Updating | When you enable ATTR_SMOOTH_UPDATE or enable Smooth Update in the Edit Graph dialog box, the graph updates first to an off-screen buffer and then to the screen. Smooth updating improves performance in the following ways: Eliminates flashing associated with plotting large plots. Optimizes speed when you use graph cursors. Optimizes speed when a graph is updated after it has been overlapped or hidden. Smooth updating has the following disadvantages: Initial plotting speed is slower. Memory usage increases. LabWindows/CVI automatically disables smooth updating of the graph when you make the color of the plot background transparent or when a visible item overlaps the plot area. ATTR_SMOOTH_UPDATE slows the initial graphing of a plot because the graph updates to the off-screen buffer before plotting to the screen. However, when you move or close a window that covers the graph, ATTR_SMOOTH_UPDATE lets LabWindows/CVI refresh the graph quickly because the plots already exist in the off-screen buffer.
Autoscaling | When you enable autoscaling, LabWindows/CVI recalculates the limits of the axes and remaps the existing graph plots with every new plot. As the number of existing plots on a graph increases, try to minimize scaling adjustments because the time necessary to recalculate and remap all the existing plots increases. You can minimize delays by disabling autoscaling, thereby preventing the recalculation and remapping of the graph plots. To disable autoscaling, call SetAxisScalingMode with the axisScaling parameter set to VAL_MANUAL or VAL_LOCK.
Anti-Aliasing | Anti-aliasing causes plots to draw more smoothly, but the plotting speed is slower. By default, graphs do not draw anti-aliased plots. To enable anti-aliasing, use the following function: SetCtrlAttribute (panelHandle, controlID, ATTR_ANTI_ALIASED_PLOTS, 1);

### Controlling How Graphs Refresh

You can use RefreshGraph, the ATTR_REFRESH_GRAPH attribute, and the refresh parameter of DeleteGraphPlot to specify when to update the graph. When you call DeleteGraphPlot, you can choose whether to redraw the plot area immediately (VAL_IMMEDIATE_DRAW), not redraw it at all (VAL_NO_DRAW), or mark the plot area to be redrawn later (VAL_DELAYED_DRAW). If you pass VAL_DELAYED_DRAW for the refresh parameter, LabWindows/CVI does not redraw the plot area until you perform one of the following operations:

- Expose the plot area after hiding or overlapping it.
- Change almost any graph attribute.
- Add a new plot while ATTR_REFRESH_GRAPH is enabled.
- Call DeleteGraphPlot with the refresh parameter set to VAL_IMMEDIATE_DRAW.
- Enable ATTR_REFRESH_GRAPH through SetCtrlAttribute.
- Move the cursor.
- Call RefreshGraph.
- Rescale the graph.

The preferred way to delete a plot and then plot a new one is to set the refresh parameter to VAL_DELAYED_DRAW when deleting, then plot the new plot. When you do this, and at the same time you enable smooth updating, you eliminate screen flashing and increase the speed of the update.

ATTR_REFRESH_GRAPH determines whether LabWindows/CVI draws new plots on a graph control immediately. When the program builds a multi-plot image for which only the final appearance is of interest, disable ATTR_REFRESH_GRAPH before you plot, and enable it after you finish plotting. That way, LabWindows/CVI redraws the graph only once, instead of each time you add a plot. Speed increases derived from using ATTR_REFRESH_GRAPH are even more noticeable when you also enable smooth updating. Plots that you add while ATTR_REFRESH_GRAPH is disabled are held in pending status. Pending plots appear only after you call RefreshGraph or when you enable the ATTR_REFRESH_GRAPH attribute.

### Optimizing Memory Usage

You can optimize memory usage by disabling the ATTR_COPY_ORIGINAL_DATA attribute and setting ATTR_DATA_MODE to VAL_DISCARD, but the savings are not significant in comparison to the overall amount of memory that LabWindows/CVI uses.

The ATTR_SMOOTH_UPDATE attribute saves an off-screen bitmap of the graph. You can save memory by disabling this attribute.

Use the ATTR_DATA_MODE attribute to retain or discard scaled plot data for new plots you add. Changing the attribute does not affect existing plots. You can save memory by setting ATTR_DATA_MODE to VAL_DISCARD, but that approach has the following disadvantages:

- When you disable ATTR_SMOOTH_UPDATE and set ATTR_DATA_MODE to discard, you get the following results:
  - The plot does not appear on the printout when you call PrintPanel or PrintCtrl.
  - The plot disappears from the screen when the graph is redrawn for any reason.
- When you enable ATTR_SMOOTH_UPDATE and set ATTR_DATA_MODE to discard, you get the following results:
  - The plot does not appear on the printout when you call PrintPanel or PrintCtrl with ATTR_BITMAP_PRINTING set to FALSE.
  - The plot disappears from the screen when the graph is rescaled.

The graph can rescale for the following reasons:

- You call SetAxisScalingMode.
- You change ATTR_XMAP_MODE or ATTR_YMAP_MODE.
- You add a new plot when autoscaling is enabled and the minimum or maximum values change.
- You change graph attributes that affect the size of the plot area.

| Note You cannot delete plots that you add to a graph while ATTR_DATA_MODE is set to VAL_DISCARD because the plot functions do not return plot handles. The graph behaves as if the plot does not exist.

The ATTR_COPY_ORIGINAL_DATA attribute determines whether the graph control keeps its own copy of the plot data. When you disable ATTR_COPY_ORIGINAL_DATA, the graph control maintains a pointer to the original array data you originally passed to the plotting function. If you change the original data or deallocate the array, either the graph displays incorrect data or an invalid pointer error occurs. ATTR_COPY_ORIGINAL_DATA affects only graph plots that are associated with arrays, such as PlotWaveform and PlotXY. The graph control uses the original data only when the graph is rescaled.

ATTR_COPY_ORIGINAL_DATA is valid only if you set ATTR_DATA_MODE to retain data.

## Graph Legend

The graph legend displays plots from the graph. To display the graph legend, enable the ATTR_LEGEND_VISIBLE attribute. By default, the legend does not appear for graph controls that you create programmatically.

If you enable the legend, the legend displays plots when plots appear on the graph. You can set ATTR_LEGEND_AUTO_DISPLAY to TRUE to allow LabWindows/CVI to insert an item in the legend control automatically when you add any plot to the graph.

You can then set the label of that plot in the legend using the following function:

SetPlotAttribute (panelHandle, controlID, plotID, ATTR_PLOT_LG_TEXT, label);

If you disable ATTR_LEGEND_AUTO_DISPLAY, you can still control whether a given plot is included in the legend by enabling or disabling the ATTR_LG_PLOT_VISIBLE plot attribute in the SetPlotAttribute function.

When you delete a plot from the graph, LabWindows/CVI also removes it from the legend.

By default, the legend sizes itself automatically whenever you add or remove a new item. You can override this behavior by disabling ATTR_LEGEND_AUTO_SIZE and setting one or more of the following attributes:

ATTR_LEGEND_TOP
ATTR_LEGEND_LEFT
ATTR_LEGEND_HEIGHT
ATTR_LEGEND_WIDTH
ATTR_LEGEND_NUM_VISIBLE_ITEMS

Enable ATTR_LEGEND_INTERACTIVE to give users the ability to edit plot attributes at run time. When you enable this attribute, a user can right-click a graph legend at run time to launch a customization menu with items such as plot color, plot style, line style, and so on. You also can use the customization menu to rename a plot.

| Note The customization menu is unavailable if the graph is in indicator mode.

If you enable data binding and you are in operate mode, the legend displays any plots connected in READ mode to a DataSocket source.

## Data Binding

Linux Data binding is not supported on Linux.

You can bind plots on graph controls to a DataSocket source. A graph control can have only one plot with an associated DataSocket connection. You must specify whether the access mode is READ mode or WRITE mode:

- READ mode—The control gets data from the DataSocket source.
- WRITE mode—The control transfers data to the DataSocket source.

Use DSBindPlot DSBindPlot to bind a specific plot on the graph control to a DataSocket source. If you specify a plot ID at bind time, the access mode must be READ. In this case, the type of plot you specify must be compatible with the data type in the DataSocket source. Valid plot types are X, Y, waveform, point, intensity, scaled intensity, and text. If you do not specify a plot ID at bind time and the access mode is READ, the graph control dynamically creates a plot that matches the data type in the DataSocket source. Use ATTR_DS_BIND... attributes to set initial preferences for this plot.

Use DSGetBoundPlotID DSGetBoundPlotID to obtain the plot ID of the graph plot. Use DSUnbind to disconnect the plot from the DataSocket source.

You must enable the DataSocket option in the Edit Installer dialog box Drivers & Components Drivers & Components tab if your applications use data binding.