WgMovieTool Procedure

Creates a window that cycles through a sequence of images.

WgMovieTool, image_data [, parent [, shell [, windowid [, rate]]]]

image_data A 3D array of images (byte). The dimensions of the array are (m, n, n_frames), where (m,n) is the size of an individual image, and n_frames is the total number of frames in the sequence.

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

rate (optional) Minimum cycling speed, specified in frames per second; the exact cycling speed varies depending on system load. (This number corresponds to the numeral "1" underneath the speed slider.) By default, under "optimum" conditions, the rate is 30 frames per second (if Pixmap is present and nonzero) or 3 frames per second (if Pixmap is not supplied or is equal to zero).

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

windowid (optional) The window ID of the PV-WAVE graphics window. (For information on window IDs, see the description for the WINDOW procedure.)

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

Dims A three-element vector specifying the size of the images to be read from the file, and the number of images to read. The elements of the vector are [m, n, n_frames], where (m,n) is the size of an individual image, and n_frames is the total number of frames in the sequence.

Do_tvscl Indicates that TVSCL should be used to scale the image values to the current color table.

1 Specifies TVSCL is used to scale the image.

0 Specifies TV is used instead (no scaling).

File A string containing the name of the file from which the image data is read. When using the File keyword, the Dims keyword must also be supplied. If present, the input variable image_data is ignored.

Maximum The maximum cycling speed, specified in frames per second; the exact cycling speed varies depending on system load. (This number corresponds to the label to the right of the speed slider.) If Maximum is not specified, the maximum rate is 100 frames per second (if Do_tvscl is not supplied or is equal to zero) or 10 frames per second (if Do_tvscl is present and nonzero).

Order The order in which the image is drawn. If present and nonzero, the image is inverted. In other words, the image is drawn from bottom to top instead of from top to bottom.

Pixmap Indicates that pixmaps should be used for the animation.

1 Specifies pixmaps are used.

0 Specifies the data is stored in a variable.

Using pixmaps dramatically improves the speed of the animation, but requires more memory from the X Window System's X server than when data stored in variables is used.

Popup If present and nonzero, the MovieTool widget is displayed in its own Main window.

Position A two-element vector specifying the x- and y-coordinates of the upper-left corner of the MovieTool window (long integer). The elements of the vector are [x, y], where x (horizontal) and y (vertical) are specified in pixels. These coordinates are either: 1) if parent is present and the Popup keyword is not specified or has a value of zero, measured from the upper-left corner of a layout (container) widget or 2) if the Popup keyword is present and nonzero (regardless of whether parent is present and/or nonzero), measured from the upper-left corner of the screen.

Size A two-element vector specifying the width and height of the display area (long integer). If not specified, the default size of the display area is m-by-n pixels, where m and n are defined by image_data.

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

View A two-element vector specifying the width and height of the viewport onto the display area (long integer). If not specified, the default size of the viewport is m-by-n pixels, where m and n are defined by image_data.

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.

For additional information on attachment keywords, see Form Layout: Attachments in Chapter 5 of the PV-WAVE GUI Application Developer's Guide.

Bottom If a widget ID is specified (for example, Bottom=wid), then the bottom of the color bar widget is attached to the top of the specified widget. If no widget ID is specified (for example, /Bottom), then the bottom of the movie widget is attached to the bottom of the parent widget.

Left If a widget ID is specified (for example, Left=wid), then the left side of the movie widget is attached to the right side of the specified widget. If no widget ID is specified (for example, /Left), then the left side of the movie widget is attached to the left side of the parent widget.

Right If a widget ID is specified (for example, Right=wid), then the right side of the movie widget is attached to the left side of the specified widget. If no widget ID is specified (for example, /Right), then the right side of the movie widget is attached to the right side of the parent widget.

Top If a widget ID is specified (for example, Top=wid), then the top of the movie widget is attached to the bottom of the specified widget. If no widget ID is specified (for example, /Top), then the top of the movie widget is attached to the top of the parent widget.

WgMovieTool (Figure 2-157) is an interactive window that lets you use the mouse to control the pace and direction of an animated series of images.

Using the WgMovieTool window is similar in many ways to using the WgAnimateTool window, but WgMovieTool is designed so that it can be included inside larger layout widgets, while WgAnimateTool is intended to be used as a stand-alone utility widget. Be sure to familiarize yourself with the attachment keywords if you plan to place WgMovieTool inside a larger layout widget.

MovieTool provides a graphical user interface (GUI) to a Standard Library procedure, movie.pro. Unlike the blocking behavior that you encounter with movie.pro, you can interact with other windows while MovieTool is open and running.

You can use the MovieTool widget in one of the following three ways:

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

• Stand-alone widget in its own window created by another application If the Popup keyword is present and nonzero, the MovieTool widget has its own Main window. The application (not the MovieTool widget) handles the event loop by calling WwLoop.

• Combined with other widgets in a layout widget Another application combines the MovieTool widget with other widgets inside a layout widget. The application (not the MovieTool widget) handles the event loop by calling WwLoop.

When the input parameter parent is present and nonzero, the widget operates in either the second or third mode listed, depending on the value of the Popup keyword. The output parameter shell can be returned only if you also supply the input parameter parent.

You can use the output parameter windowid to keep track of the PV-WAVE window ID that is assigned to the MovieTool. You can create multiple instances of the MovieTool; each one will be assigned a different PV-WAVE window ID.

The MovieTool window has two main parts the display area and the control area.

The display area is the largest area of the window; it is where the animation sequence takes place.

Use the following controls to operate the MovieTool window:

• Frames/sec slider Decrease or increase the rate of display. The number shown to the left of the slider is the minimum cycling speed for the animation sequence; this number is controlled with the Rate keyword. The number shown to the right of the slider is the maximum cycling speed for the animation sequence; this number is controlled with the Maximum keyword.

• Left-pointing arrow Cycle through the images from last to first.

• Stop button Freeze display at the current image.

• Right-pointing arrow Cycle through the images from first to last.

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

When you are finished interacting with the WgMovieTool window, close it using the window manager menu.

PRO Sample_wgmovietool, parent, tool_shell
heart = BYTARR(256, 256, 15)

; Define a variable to hold the data.

IF !Version.platform EQ 'VMS' THEN $
    OPENR, u, GETENV('WAVE_DIR')+$
    '[data]heartbeat.dat', /Get_lun $
ENDIF ELSE BEGIN
OPENR, u, !Dir+'/data/heartbeat.dat', /Get_lun
ENDELSE
READU, u, heart

; Read the heartbeat.dat file that contains images showing a
; beating human heart.

CLOSE, u
FREE_LUN, u

; Close the file and free the LUN.

IF N_ELEMENTS(parent) NE 0 THEN BEGIN
WgMovieTool, heart, parent, tool_shell, $
    /Do_tvscl, /Pixmap, /Popup

; Create WgMovieTool 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
WgMovieTool, heart, /Do_tvscl, /Pixmap

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

ENDELSE
END

MOVIE, WgAnimateTool

For more information about how to transfer image data to variables, refer to Input and Output of Image Data in Chapter 8 of the PV-WAVE Programmer's Guide.

For more information about pixmaps, refer to Appendix , Output Devices and Window Systems.

For more information about color table indices, refer to Experimenting with Different Color Tables in Chapter 11 of the PV-WAVE User's Guide.

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.