WgSurfaceTool Procedure

Creates a surface window with a built-in set of controls: these controls allow you to interactively modify surface parameters and view the result of those modifications.

WgSurfaceTool, surface_data [, parent [, shell ]]

surface_data A 2D variable containing surface data.

parent (optional) The widget or shell ID of the parent widget (long). If parent is not specified, WgSurfaceTool runs on its own (i.e., in its own event loop).

shell (optional) The ID of the newly created widget. If the procedure fails, zero (0) is returned.

Auto_congrid If present and nonzero, the z variable is resized to 50-by-50 (with CONGRID) prior to drawing the surface. This enables PV-WAVE to draw the surface much faster, although there is a chance that some surface detail is lost.

Auto_redraw If present and nonzero, the surface is automatically redrawn any time one of the surface parameters is adjusted.

Cmap The index of the color table to load when the widget is created; a positive integer in the range (0...15).

Elevation If present and nonzero, the surface is drawn using simple elevation shading. Elevation and Gouraud are mutually exclusive.

Gouraud If present and nonzero, the surface is drawn using Gouraud shading. Gouraud and Elevation are mutually exclusive.

Lines If present and nonzero, lines are drawn instead of a grid.

Lower If present and nonzero, only the lower portion of the grid is drawn. Lower and Upper are mutually exclusive keywords.

Nogrid If present and nonzero, no grid is drawn on the surface.

Position A two-element vector specifying the x- and y-coordinates of the upper-left corner of the SurfaceTool window (long integer). The elements of the vector are [x, y], where x (horizontal) and y (vertical) are specified in pixels. These coordinates are measured from the upper-left corner of the screen.

Skirt If present and nonzero, a skirt is drawn connecting the surface to the x- and y-axes. Refer to Figure 2-169 for an example of a surface with and without a skirt.

Title A string containing the title that appears in the header of the SurfaceTool window. Default value is "Surface Tool".

Upper If present and nonzero, only the upper portion of the grid is drawn. Upper and Lower are mutually exclusive keywords.

Xrot The initial counter-clockwise rotation of the surface around the x-axis, measured in degrees.

Zrot The initial counter-clockwise rotation of the surface around the z-axis, measured in degrees.

For additional information on the color and font keywords, see Setting Colors and Fonts in Chapter 5 of the PV-WAVE GUI Application Developer's Guide.

Background Specifies the background color name.

Basecolor Specifies the base color.

Font Specifies the name of the font used for text.

Foreground Specifies the foreground color name.

WgSurfaceTool (Figure 2-167) is an interactive window that lets you use the mouse to control the orientation and appearance of a displayed surface.

You can use the SurfaceTool widget in one of the following two ways:

• From the WAVE prompt Enter the procedure name at the WAVE prompt to display the SurfaceTool widget. The SurfaceTool widget handles its own event loop by calling WwLoop.

• Stand-alone widget in its own window created by another application The SurfaceTool widget has its own Main window, but the application (not the SurfaceTool widget) handles the event loop by calling WwLoop.

The output parameter shell can be returned only if you also supply the input parameter parent.

The SurfaceTool window has three main parts the display area, the control area, and the message area.

The display area is the largest area of the window; it is where the surface is displayed.

Use the following controls to operate the SurfaceTool window:

• Surface (menu) From the menu, choose the method by which the surface is drawn. The choices are: Fishnet (mesh), Lines (lines in one direction only), and None (no lines appear superimposed on a shaded surface).

• Sides (menu) From the menu, choose the representation of the top and bottom sides of the surface. The choices are: Both (lines on both top and bottom), Upper (lines on upper surface only), and Lower (lines on lower surface only).

• Skirt Controls whether a skirt is added to the surface. A skirt helps establish a frame of reference between the surface and thex-, y-, and z-axes. Refer to Figure 2-169 for an example of a surface with and without a skirt.

• Shade (menu) From the menu, select the algorithm by which the surface is shaded. The choices are: None (no shading), Gouraud, and Elevation.

• X and Z Rotation These controls allow you to rotate the surface (counter-clockwise around the x- or z-axis) a specified number of degrees. The current rotation is shown in the text field to the right of the slider. To modify the rotation, either enter a new value in one of the text fields, or use either slider. If you enter a new value into a text field, press Return to apply the new value to the slider and the surface. If you use the sliders, the change is applied immediately as the slider moves.

• Auto Redraw Controls whether the contents of the display area are redrawn every time a modification is made to one of the controls in the SurfaceTool control area.

• Auto Congrid The surface is resized to 50-by-50 (with CONGRID) prior to drawing the surface, for faster display of large datasets. The default is for Auto Congrid to be enabled. Auto Congrid does not affect the actual data; it only affects the display of the data.

• Redraw Causes the contents of the SurfaceTool display area to be redrawn.

• Dismiss Destroy the SurfaceTool window and erase it from the screen.

The message area displays the PV-WAVE command that is being used to display the surface.

Enter the commands shown below into a file, and compile the procedure with the .RUN command. If the variable parent is defined, WgSurfaceTool is created as a child of parent; otherwise, WgSurfaceTool runs on its own (i.e., in its own event loop).

When you are finished interacting with the WgSurfaceTool window, close it by clicking on the Dismiss button.

PRO Sample_wgsurfacetool, parent, tool_shell
x = DIST(75)

; Create a "dummy" variable to view as view as a surface using WgSurfaceTool.

IF N_ELEMENTS(parent) NE 0 THEN BEGIN
WgSurfaceTool, x, parent, tool_shell

; Create WgSurfaceTool as a child of the widget known as "parent".
; The window of the newly created widget is returned via the optional
; output parameter "tool_shell".

ENDIF ELSE BEGIN
WgSurfaceTool, x

; Create WgSurfaceTool and display it as its own Main window. 
; In other words, the WgSurfaceTool window runs on its own (i.e., in
; its own event loop).

ENDELSE
END

SHADE_SURF, SURFACE

For more information about how to write an application program based on WAVE Widgets, refer to Chapter 5, Using WAVE Widgets, in the PV-WAVE GUI Application Developer's Guide. For more information about how to write an application program based on the PV-WAVE Widget Toolbox, refer to Chapter 6, Using the Widget Toolbox, in the PV-WAVE GUI Application Developer's Guide.