Interacting with Measurement Studio Graphs in Visual Basic Heather Edwards

Application Note 163 Interacting with Measurement Studio Graphs in Visual Basic Heather Edwards Introduction You have collected your measurements, displayed them on a Measurement Studio 1 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. Figure 1. Displaying the Position of the Mouse Pointer 1. 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. ComponentWorks, Measurement Studio, National Instruments, and ni.com are trademarks of National Instruments Corporation. Product and company names mentioned herein are trademarks or trade names of their respective companies. 342059A-01 Copyright 2000 National Instruments Corporation. All rights reserved. July 2000

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 application note 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 Application Note 163 2 www.ni.com

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: Set on the Graph Property Page TrackMode Values Set Programmatically Table 1. CWGraph TrackMode Events Recognized Events and Description Cursors cwgtrackdragcursor Generated Event: CursorChange PanXY PanX PanY ZoomXY ZoomX ZoomY cwgtrackpanplotareaxy cwgtrackpanplotareax cwgtrackpanplotareay cwgtrackzoomrectxy cwgtrackzoomrectx cwgtrackzoomrecty 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. 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. National Instruments Corporation 3 Application Note 163

Table 1. CWGraph TrackMode Events (Continued) Set on the Graph Property Page Plot & Cursor Events TrackMode Values Set Programmatically cwgtrackallevents Recognized Events and Description 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: 1. CursorMouse event (if the mouse is near a cursor) 2. PlotMouse event (if the mouse is near a plot) 3. 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. Application Note 163 4 www.ni.com

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 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 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 Figure 1, 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 National Instruments Corporation 5 Application Note 163

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 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 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 Table 2. 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 Property Page Snap Mode Values Table 2. SnapMode Options for Dragging Cursors Programmatic Description 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). Application Note 163 6 www.ni.com

Property Page 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. Point on selected plot Nearest Y to fixed X Snap Mode Values Table 2. SnapMode Options for Dragging Cursors (Continued) Programmatic cwcsnappointsonplot cwcsnapnearestyforfixedx Example Positioning Cursors Programmatically Description 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. 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. 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) 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. National Instruments Corporation 7 Application Note 163

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 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. Application Note 163 8 www.ni.com

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) National Instruments Corporation 9 Application Note 163

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. Select a region of interest with your mouse. The graph resizes to display the region of interest with more detail. 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 Enabling CWGraph3D Interactions with TrackMode 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. Application Note 163 10 www.ni.com

As you develop your program, set the TrackMode to one of the following to define how the graph responds to user interaction: Set on the Graph Property Page TrackMode Values Set Programmatically Table 3. CWGraph3D TrackMode Events Recognized Events and Descriptions 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: 1. PlotMouse event (if the mouse is near a plot) 2. 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. National Instruments Corporation 11 Application Note 163

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 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. Application Note 163 12 www.ni.com

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 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 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 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 Conclusion 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: National Instruments 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 National Instruments Corporation 13 Application Note 163