Interacting with Measurement Studio Graphs in Visual Basic

You have collected your measurements, displayed them on a Measurement Studio (Measurement Studio includes tools to build measurement applications in ANSI C, Visual C++, and Visual Basic. The Measurement Studio Visual Basic tools are also known as ComponentWorks.) 2D Graph or 3D Graph control in Visual Basic, and now you need to interact with the visualized data. Perhaps you need to pinpoint exact data points on a plot or zoom in on a region of interest. This application note shows you how to create sophisticated interactive interfaces that include:

• Cursors (2D Graph only)
• Zooming
• Panning
• Rotating (3D Graph only)
• Automatic processing in response to mouse events, such as moving your mouse pointer over the graph or plot, pressing the mouse button, or releasing the mouse button

Consider the example program shown in Figure 1. This program plots a set of measurements on the 2D Graph and displays the coordinates of the mouse pointer when it passes over the plot. As you move your mouse pointer over the plot, the program displays coordinates describing the current position of your mouse pointer.

Each Measurement Studio graph offers several different modes that you can use to specify exactly how you want the graph to respond to user interaction. Each mode defines how the graph responds to interaction during runtime and which events are generated. Depending on the mode you select, you can configure a graph to respond to all mouse events occurring anywhere on the graph (called plot area events), to mouse events occurring only on data plots (called plot events), or to a particular interaction such as panning, zooming, rotating, or interacting with cursors. You can select the mode in the Graph property page or set it programmatically with the TrackMode property.

As you develop your program, consider how you want to interact with the graph and then select the appropriate TrackMode. Then develop event procedures to define how your program should respond when important events occur. Refer to Table 1, CWGraph TrackMode Events for a list of 2D Graph TrackMode options. Refer to Table 3, CWGraph3D TrackMode Events for a list of 3D Graph TrackMode options. Both tables list the events that are generated with each TrackMode option.

For the program shown in Figure 1, the graph uses the Plot & Cursor Events TrackMode, which enables event generation for all plot events. Every time you move the mouse pointer over the plot, a PlotMouseMove event is generated. When that event is generated, the corresponding event procedure is called to process the event. For this program, the event procedure displays the updated position of the mouse pointer.

Note: The Plot & Cursor Events TrackMode generates events for MouseMove, MouseDown, and MouseUp. MouseMove occurs when you move the mouse over the specified area. MouseDown occurs when you press a mouse button, and MouseUp occurs when you release that mouse button. These same mouse events might apply to plots, the entire plot area, or cursors (in two-dimensional graphs), depending on the TrackMode option.

This tutorial contains the following examples:

• Interacting with the 2D Graph
  • Displaying the (X,Y) Location of Your Mouse on a Graph Plot
  • Using a Cursor to Identify Data Locations in a Plot
  • Positioning Cursors Programmatically
  • Using Two Cursors to Identify a Range of Data
  • Panning and Zooming
• Interacting with the 3D Graph
  • Displaying the (X,Y,Z) Location of Your Mouse on a 3D Graph Plot
  • Zooming, Panning, and Rotating

 Enabling CWGraph Interactions with TrackMode

Depending on the selected TrackMode option, you can interact with the two-dimensional graph (CWGraph) and data by moving cursors to mark specific points on the graph or a particular plot, panning the graph to view data not currently displayed, or zooming in on a selected portion of the graph.

As you develop your program, set the TrackMode to one of the following options to define how the graph responds to your mouse:

TrackMode Values		Recognized Events and Description
Set on the Graph Property Page	Set Programmatically
Cursors	cwGTrackDragCursor	Generated Event: CursorChange Default. Enables you to drag a cursor with your mouse if the graph contains a cursor. Every time a cursor is interactively moved with the mouse on the user interface, the cursor generates a CursorChange event that communicates the cursor’s location to your program. From your event procedure, you might display the X and Y position of the cursor on the user interface. The CursorChange event is not generated if you change the cursor position with the SetPosition method
PanXY PanX PanY ZoomXY ZoomX ZoomY	cwGTrackPanPlotAreaXY cwGTrackPanPlotAreaX cwGTrackPanPlotAreaY cwGTrackZoomRectXY cwGTrackZoomRectX cwGTrackZoomRectY	Generated Event: No events are generated when you pan the plots or zoom in on data. Enables panning or zooming, but does not enable any mouse events. You can pan and zoom horizontally (X), vertically (Y), or both horizontally and vertically (XY) without writing any code.
Plot Area Events	cwGTrackPlotAreaEvents	Generated Events: PlotAreaMouseDown, PlotAreaMouseMove, PlotAreaMouseUp Enables plot area event generation. The plot area is anywhere on the graph interface on which data can be displayed. Plot area events occur when you press a mouse button, release the mouse button, or move the mouse pointer anywhere on the graph.
Plot & Cursor Events	cwGTrackAllEvents	Generated Events: PlotAreaMouseDown, PlotAreaMouseMove, PlotAreaMouseUp, PlotMouseDown, PlotMouseMove, PlotMouseUp, CursorMouseDown, CursorMouseMove, CursorMouseUp Note: The CursorChange event is not generated with this TrackMode option. If you want to drag a cursor from the user interface with this TrackMode, you must define event procedures to programmatically set the cursor position. Enables plot area, plot, and cursor event generation. Plot area events occur anywhere on the graph interface. Plot and cursor events occur when you press a mouse button, release the mouse button, or move the mouse pointer on a plot or cursor. The control generates the events in the following order: CursorMouse event (if the mouse is near a cursor) PlotMouse event (if the mouse is near a plot) PlotAreaMouse event Note: Remember as you interact with plots that a plot is a collection of individual points. The plot mouse events are fired only at the individual data points, not the line that connects them.

Note: Some CWGraph events are generated regardless of the TrackMode property setting: Click, DblClick, KeyDown, KeyUp, KeyPress, and ReadyStateChange.
 

Example -- Displaying the (X,Y) Location of Your Mouse on a Graph Plot

To create the example shown in Figure 1, place a CWGraph control (named CWGraph1), a command button (named cmdPlotData), and two Visual Basic labels (named lblXPos and lblYPos) on the form to display the X and Y location, and create the following two event procedures. The first event procedure is called when you press the Plot Data button on the user interface. It plots the data on the graph and enables event generation for all plot and cursor mouse events:

Private Sub cmdPlotData_Click()
    CWGraph1.TrackMode = cwGTrackAllEvents
    'data is a global array of measurements
    CWGraph1.PlotY data
End Sub

The second event procedure is called every time the mouse position changes. This procedure uses two of the returned parameters -- xData and YData -- to display the current location of the mouse pointer:

Private Sub CWGraph1_PlotMouseMove(Button As Integer, Shift As Integer, xData As Variant, YData As Variant, PlotIndex As Integer, PointIndex As Long)
    'Display coordinates in labels on the interface
    lblXPos.Caption = xData
    lblYPos.Caption = YData
End Sub

Tip You can control the numerical formatting of the X and Y coordinates with the Visual Basic Format function. For example, to display the coordinates as shown in Figure1, include the following formatting:

lblXPos.Caption = Format(xData, "##0.0#")
lblYPos.Caption = Format(YData, "##0.0#")

Example -- Using a Cursor to Identify Data Locations in a Plot

Cursors are useful for marking specific points or regions on a graph or a plot. Figure 2 shows a modified version of the first example program. This example works identically to the previous program except that a cursor locates the X and Y position rather than a mouse pointer.

Figure 2. Using Cursors to Mark Specific Points or Regions on a Graph or Plot

The following event procedures programmatically add a cursor, enable the cursor TrackMode, and display the cursor location in the CursorChange event procedure:

Private Sub cmdPlotData_Click()
    'Enable cursor events
    CWGraph1.TrackMode = cwGTrackDragCursor
    'data is a global array of measurements
    CWGraph1.PlotY data
    'Do not add a cursor if one already exists
    If CWGraph1.Cursors.Count = 0 Then
         CWGraph1.Cursors.Add
    End If
End Sub

Private Sub CWGraph1_CursorChange(CursorIndex As Long, XPos As Variant, YPos As Variant, bTracking As Boolean)
    'Display coordinates in labels on the user interface
    lblXPos.Caption = XPos
    lblYPos.Caption = YPos
End Sub

If you try to move the cursor with your mouse, you will notice that you can move the cursor freely on the plot area. Sometimes it might make sense to limit the movement of the cursor to the plot. You can use the SnapMode property to restrict the cursor movement as described in Table2. For this example, you can add the following code at the end of the first event procedure to limit the cursor position to the nearest data point on the plot:
     
'Snap cursor to the nearest data point
    CWGraph1.Cursors(1).SnapMode = cwCSnapNearestPoint
 

Table 2. SnapMode Options for Dragging Cursors

Snap Mode Values		Recognized Events and Description
Set on the Graph Property Page	Set Programmatically
Floating	cwCSnapFloating	Default. You can drag the cursor anywhere within the defined axes, or you can programmatically position the cursor anywhere on the graph. For example, although the cursor will not be visible, you can use the SetPosition method to set the cursor to the (X,Y) coordinate (1000,500) even if the x-axis maximum is 800 and the y-axis maximum is 400.
Fixed	cwCSnapFixed	The cursor behaves the same as the floating SnapMode, except the position is limited to the actual region defined by the x-axis and y-axis minimum and maximum whether you drag the cursor from the user interface or set its position programmatically. For example, if you try to set the cursor to (1000,500) with the SetPosition method on a graph with an x-axis maximum of 800 and a y-axis maximum of 400, the cursor is positioned at 800,400).
Point on any plot	cwCSnapNearestPoint	When you are dragging the cursor, it moves to the point on any plot closest (in plot area distance) to the mouse pointer. If you are moving the cursor programmatically with the SetPosition method, it moves to the point closest to the X and Y values passed to the SetPosition method. A consequence of the cursor moving to the plot point closest to the desired position is that the cursor can jump discretely from one position on the x-axis to another position on the other side of the mouse. That is, the cursor snaps to the nearest point on the plot, which might be on the plot to the left of the mouse pointer or to the right.
Point on selected plot	cwCSnapPointsOnPlot	The cursor moves to the closest point on the plot specified by the Cursor.Plot property. You must specify an associated plot either in the property page if you created the cursor there or programmatically, as shown in the following code: 'Associate the cursor with the first plot. Set CWGraph1.Cursors(1).Plot = CWGraph1.Plots(1) A consequence of the cursor moving to the plot point closest to the desired position is that the cursor can jump discretely from one position on the x-axis to another position on the other side of the mouse. That is, the cursor snaps to the nearest point on the plot, which might be on the plot to the left of the mouse pointer or to the right.
Nearest Y to fixed X	cwCSnapNearestYForFixedX	The cursor moves across the x-axis on the plot specified by the Cursor.Plot property. You must specify an associated plot either in the property page if you created the cursor there or programmatically, as shown in the following code: 'Associate the cursor with the first plot. Set CWGraph1.Cursors(1).Plot = CWGraph1.Plots(1)

 

Example -- Positioning Cursors Programmatically
You can combine plot and cursor events in many ways to create a sophisticated interactive interface for your application. If you want to provide cursors and still allow other mouse interactions in your application, use the Plot & Cursor TrackMode. When TrackMode is set to generate events for plots and cursors, the CursorChange event is no longer generated so you can no longer interactively drag the cursor on the graph without writing event procedures to do so.

Rather than adding cursors programmatically as you did in the previous example, you can interactively create and design your cursor through the property pages. From the Cursors property page, you can select the crosshair style, point style, and color to design a cursor that works best for your program.

For this example, use the same interface as shown in Figure 2, and open the Cursors property page to add and customize the cursor. Your property page should look similar to the one in Figure 3.
 

Figure 3. Interactively Adding and Configuring a Cursor in the Property Pages
 

On the Graph property page, set TrackMode to Plot & Cursor Events.

Add the following event procedure to programmatically move the cursor and display its X and Y location when you press your left mouse button directly on the cursor and drag:

Private Sub CWGraph1_CursorMouseMove(Button As Integer, Shift As Integer, XPos As Variant, YPos As Variant, CursorIndex As Integer, CursorPart As Long)
    If (Button = vbLeftButton) Then
         CWGraph1.Cursors(CursorIndex + 1).SetPosition XPos, YPos
         lblXPos.Caption = XPos
         lblYPos.Caption = YPos
    End If
End Sub

Note The CursorMouseMove event returns the CursorIndex parameter to indicate the index of the cursor, which is useful if your graph contains more than one cursor. In the call to SetPosition, use (CursorIndex + 1) to specify which cursor to move because cursors are a one-based collection.

Example -- Using Two Cursors to Identify a Range of Data
You can set up two cursors to identify a range of data in a graph that you can then analyze. In this example, you create two cursors and use them to select a range of data on the plot. You then calculate the maximum value in the range. Figure 4 shows how the program might look.

Figure 4. Identifying a Range of Data with Two Cursors
 

To create the program shown in Figure 4, place a CWGraph (named CWGraph1), a command button (named cmdPlotData), and three Visual Basic labels (named lblStart, lblEnd, and lblMaximum).

When you are working with multiple objects, such as plots or cursors, you should give each object a descriptive name so that you can easily reference the correct object in your code. On the Cursors property page, add and configure two cursors. Name the first cursor StartCursor, and the second EndCursor. Change the crosshair style of both cursors to Major X only, and select a different color for each cursor.

On the Graph property page, verify that TrackMode is set to Cursors, which enables you to drag the cursors from the user interface without writing any code.
 

Note If you want to enable both plot and cursor interactions in your program, set TrackMode to Plots & Cursors and define the CursorMouseMove event procedure to programmatically move the cursor, extract the range, and identify the maximum value in the range.

Define the CursorChange event to extract the subset and find the maximum value of the data you just selected:

Private Sub CWGraph1_CursorChange(CursorIndex As Long, XPos As Variant, YPos As Variant, bTracking As Boolean)
    'Variables for extracting the range and finding
    'the max value
    Dim subset, start, length As Variant
    'Display X locations for both cursors
    lblStart.Caption =
         CWGraph1.Cursors("StartCursor").XPosition
    lblEnd.Caption = CWGraph1.Cursors("EndCursor").XPosition
    'Identify the X position that starts the range
    start = CWGraph1.Cursors("StartCursor").XPosition
    'Calculate the length of the range
    length = CWGraph1.Cursors("EndCursor").XPosition - start
    'Extract the data subset--data is a global array
    'of measurements
    subset = CWArray1.Subset1D(data, start, length)
    'Find and display the maximum value in the subset
    lblMaximum.Caption = CWArray1.MaxArray(subset)
End Sub

Note CWArray is the Measurement Studio Analysis Array control for Visual Basic. It contains functions that you can use to perform arithmetic operations on arrays. For example, the CWArray.Subset1D function extracts the portion of the data selected by the cursors, and the MaxArray function returns the maximum value found in the selected data.

 

Example -- Panning and Zooming
Panning is useful when the entire plot is not visible in the plot area, and zooming is useful when you want to focus in on a particular region of a plot. Zooming allows you to view a plot in more detail by interactively changing the range of one axis or both axes. You can configure the CWGraph control to pan or zoom horizontally (X), vertically (Y), or both horizontally and vertically (XY), depending on the selected TrackMode.

Note There are no pan or zoom events on the 2D Graph. When you use a panning or zooming TrackMode, you are only enabling the pan and zoom interactions.

Figure 5 shows an example program containing two plots of data. TrackMode is set to ZoomRectXY to enable both horizontal and vertical zooming. As you select a region of data on which to zoom in, the data within this rectangle is magnified to fill the entire plot area and the x- and y-axes are redefined.

Figure 5. Selecting a Region of Data and Zooming In
 

If you want to restore a zoomed view to the original view, add a Reset button that calls the following event procedure:

Private Sub cmdReset_Click()
    'Reset the axes.
    CWGraph1.Axes(1).AutoScaleNow
    CWGraph1.Axes(2).AutoScaleNow
End Sub
 

Enabling CWGraph3D Interactions with TrackMode

Visualizing data is an indispensable tool for quickly gaining a better understanding of what data represents and for communicating results to others. Interacting with that data often offers deeper insight. By interactively locating specific data points or regions of interest, you can more closely examine the results and what those results really mean through additional processing and analysis. The Measurement Studio 2D and 3D Graphs offer multiple TrackMode options; interactive features such as cursors, panning, zooming, and rotating; and flexible events to handle interactions – empowering you to interact with data in the way that is most meaningful to you.
 

If you want more information about the Measurement Studio ActiveX controls and using them in Visual Basic, refer to the following resources:
 

• NI Developer Zone at www.ni.com for more applications notes and example programs
• Measurement Studio Reference (if you have Measurement Studio installed) for complete reference information about the controls and their properties, methods, and events

• If you want to reset the axes to the original view, add a Reset button that calls the SetDefaultView method on the graph, as in the following example:

  Private Sub cmdReset_Click()
      CWGraph3D1.SetDefaultView
  End Sub

  You can provide feedback through the user interface about zooming, panning, and rotating with the appropriate event procedures. In the following examples, the Zoom event displays the new distance of the viewing position from the origin after zooming on a graph, the Pan event displays the new (X,Y,Z) coordinate of the center of the view, and the Rotate event displays the new latitude and longitude of the viewing position.
  
   

  Private Sub CWGraph3D1_Zoom(NewDistance As Variant)
      'Update distance information after zoom event
      lblDistance.Caption = NewDistance
  End Sub

  Private Sub CWGraph3D1_Pan(NewXCenter As Variant, NewYCenter As Variant, NewZCenter As Variant)
      'Update center information after pan event
      lblXCenter.Caption = NewXCenter
      lblYCenter.Caption = NewYCenter
      lblZCenter.Caption = NewZCenter
  End Sub

  Private Sub CWGraph3D1_Rotate(NewLatitude As Variant, NewLongitude As Variant)
      'Update latitude and longitude information
      'after a rotate event
      lblLatitude.Caption = NewLatitude
      lblLongitude.Caption = NewLongitude
  End Sub
   

 Conclusion

Depending on the selected TrackMode option, you can interact with the three-dimensional graph (CWGraph3D) and data by panning the graph to view data not currently displayed, zooming in on a selected portion of the graph, and rotating the graph, or by enabling mouse events.

Tip Refer to the 3D Graph Events example installed in Vb\Samples\UI\3DGraph\Events to see how to implement and use each of the TrackMode options.

As you develop your program, set the TrackMode to one of the following to define how the graph responds to user interaction:
 

TrackMode Values		Recognized Events and Description
Set on the Graph Property Page	Set Programmatically
Plot Area Events	cwG3DTrackPlotAreaEvents	Generated Events: Click, DblClick, MouseDown, MouseMove, MouseUp, PlotAreaMouseDown, PlotAreaMouseMove, PlotAreaMouseUp Enables plot area event generation. The plot area is anywhere on the graph interface on which data can be displayed. Plot area events occur when you press a mouse button, release the mouse button, or move the mouse pointer anywhere on the graph.
All Events	cwG3DTrackAllEvents	Generated Events: Click, DblClick, MouseDown, MouseMove, MouseUp, PlotAreaMouseDown, PlotAreaMouseMove, PlotAreaMouseUp, PlotMouseDown, PlotMouseMove, PlotMouseUp Enables plot and plot area event generation. Plot area events our when you press a mouse button, release the mouse button, or move the mouse pointer anywhere on the entire graph interface. Plot events occur when you press a mouse button, release the mouse button, or move the mouse pointer on a plot. The control generates the events in the following order: PlotMouse event (if the mouse is near a plot) PlotAreaMouse event
Zoom Pan Rotate	cwG3DTrackZoomPanRotate	Generated Events: Zoom, Pan, Rotate Default. Enables interactive zooming, panning, and rotating without writing any code. The Zoom event is generated when you zoom in or out on the plot. To zoom the graph, press and hold the <Alt> key and the left mouse button while dragging the mouse forward and backward. If your mouse has a wheel, you also can zoom the graph by rotating the wheel. The Pan event is generated when you pan the graph up and down or left and right. To pan the graph, press and hold the <Shift> key and the left mouse button while dragging the mouse. The Rotate event is generated when you rotate the graph. To rotate the graph, press and hold the left mouse button and drag.

Note Some CWGraph3D events are generated regardless of the TrackMode property setting: KeyDown, KeyUp, KeyPress, and ReadyStateChange.

Example -- Displaying the (X,Y,Z) Location of Your Mouse on a 3D Graph Plot
This example displays the location of the mouse pointer as the mouse is moved across three-dimensional plots, as shown in Figure 6.
 

Figure 6. Displaying the (X,Y,Z) Position of the Mouse Pointer on Three-Dimensional Plots

To create this example, use a 3D Graph control (named CWGraph3D1), a command button (named cmdPlotData), and four Visual Basic labels (named lblPlot, lblXPos, lblYPos, and lblZPos) to display the plot name and the (X, Y, Z) location.

On the Graph--General property page, set TrackMode to All Events.

On the Plots page, name the first plot Plot1 and add a second plot named Plot2. Assign a different fill color to the second plot.

Add the following event procedure to display the location of the mouse pointer, including the plot name and the X, Y, and Z position:

Private Sub CWGraph3D1_PlotMouseMove(Button As Integer, Shift As Integer, XData As Variant, YData As Variant, ZData As Variant, PlotIndex As Integer, PointI As Long, PointJ As Long)
    'Display the name of the plot
    lblPlot.Caption = CWGraph3D1.Plots(PlotIndex).Name
    lblXPos.Caption = XData
    lblYPos.Caption = YData
    lblZPos.Caption = ZData
End Sub

 

Example -- Zooming, Panning, and Rotating

The 3D Graph control offers zooming, panning, and rotating with the same TrackMode option, which means that you can do all three on the graph during runtime. Set TrackMode to cwG3DTrackZoomPanRotate, run the program, and try zooming, panning, and rotating:

• To zoom on the graph, press and hold the <Alt> key and the left mouse button while dragging the mouse forward and backward. If your mouse has a wheel, you also can zoom on the graph by rotating the wheel.
• To pan the graph, press and hold the <Shift> key and the left mouse button while dragging the mouse.
• To rotate the graph, press and hold the left mouse button and drag.