WwDrawing Function

Creates a drawing area, which allows users to display graphics generated by PV‑WAVE.

Usage

wid = WwDrawing(parent, windowid, drawCallback, wsize, dsize)

Input Parameters

parent — The widget ID of the parent widget.

windowid — The window ID of the PV‑WAVE graphics window. When the window index is undefined or less than zero, the first free window index (ascending) is used and returned as windowid.

If you specify a window ID between 0 and 31 and this window ID is already in use you will see an error message and WwDrawing will return 0.For information on window IDs, see the WINDOW procedure.

drawCallback — A string containing the name of the PV‑WAVE callback routine that is executed when the drawing area is exposed to display the graphics.

Avoid placing any calls directly in the drawCallback procedure that could create a window, such as a dialog box, in front of the drawing area widget. The reason for this is related to the way in which the X server handles backing store — the server’s method of repainting windows that are hidden (either entirely or partially) and then re-exposed. If your X server does not support backing store, or if it is running out of memory, it calls on your application to repaint windows. If the drawCallback procedure creates a graphics window and then places another window, such as a dialog box in front of the graphics window, when you dismiss the dialog box the X server calls the drawCallback procedure to repaint the drawing area, resulting in an infinite loop.

wsize — A vector containing two integers that represent the width and height of the drawing area window. The window size is limited to 32767 pixels on a side, or the available memory for the pixmap, whichever is less.

dsize — A vector containing two integers that represent the width and height of the image to be displayed in the drawing area. If this is larger than wsize, you can use the scroll bars to move the image around in the display window.

Returned Value

wid — The ID of the drawing area widget.

Keywords

Area — Returns the drawing area widget’s ID.

Border — Specifies the width of the borders in pixels for the parent widget and the child widgets. The default is 0.

Layout_name — Specifies the name of the Form or ScrolledWindow container widget used to hold the drawing area widget. The Layout_name specified is the top-level widget layout name used as part of the resource specification. (Default: drawindow.)

Name — A string containing the name of the DrawingArea widget. The Name specified is the widget name used as part of the resource specification. (Default: draw.)

NoMeta — (Windows only) Turns metafiles off for the window that contains the drawing area. Use this keyword when running animations or displaying images.

A metafile is an internal, vector-based record of all the graphics commands sent to a window. By default, a metafile is kept for each window to speed the redrawing of the window when it is resized. The metafile is also used when printing to avoid resolution problems that occur when printing a bitmap image.

Noscroll — If present and nonzero, the drawing area does not use scroll bars. The drawing area window is created the same size as the drawing area. In other words, the value of dsize equals wsize.

Tab navigation within a WwDrawing widget only traverses the scroll bars, not through the drawing area. Therefore, if the WwDrawing widget is created without scrollbars using the Noscroll keyword, tab navigation has no effect.

Position — If the drawing box widget is to be placed in a bulletin board layout, use this keyword to specify the x, y coordinates of the drawing box widget within the bulletin board.

Tab_WinOff — (Windows only) If this keyword is present and nonzero, the tab navigation feature is turned off for this widget.

Only WwDrawing widgets with scrollbars allow tab navigation.

Color Keywords

Background — Specifies the background color name.

Foreground — Specifies the foreground color name.

Attachment Keywords

Bottom — If a widget ID is specified (for example, Bottom=wid), then the bottom of the drawing box widget is attached to the top of the specified widget. If no widget ID is specified (for example, /Bottom), then the bottom of the drawing box 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 drawing box 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 drawing box 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 drawing box 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 drawing box 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 drawing box widget is attached to the bottom of the specified widget. If no widget ID is specified (for example, /Top), then the top of the drawing box widget will attach to the bottom of the parent widget.

Get/Set Value

getvalue — Gets the window ID of the drawing area widget.

setvalue — Sets a two-element vector containing the width and height of the drawing area.

The return value from WwGetValue is the window ID of the drawing area widget and is not a PV-WAVE Widget ID. This value cannot be used with PV-WAVE routines that expect a PV-WAVE Widget ID. This window ID is created by the native windowing system to be used for sharing graphical windows between applications. This value is typically used via the Get_Win_ID/Set_Win_ID keywords to the PV‑WAVE WINDOW procedure.It is invalid to use the window ID with any PV-WAVE routine that expects a PV-WAVE Widget ID. PV-WAVE is incapable of checking the validity of a Widget ID, which is passed directly to the windowing system. Passing an invalid Widget ID to the windowing system typically results in a segmentation violation.

Callback Parameters

Any drawing area widget callback procedure must have the following two parameters:

wid — Drawing area widget ID.

index — PV‑WAVE window index.

Discussion

The window size is limited to 32767 pixels on a side, or the available memory for the pixmap, whichever is less.

Example

This example creates a widget that displays an image. Whenever the drawing area widget is displayed, the callback is executed. In this case, the callback opens and reads an image file.

Enter the callback procedure into a file, and compile the procedure with the .RUN command. Then, enter the widget commands at the WAVE> prompt. To dismiss the drawing area widget, select the appropriate function (such as Close) from the window manager menu.

PRO DrawCB, wid, data
   COMMON draw, img
   PRINT, 'Draw'
   TV, img
END
PRO ww_ex24
   top=WwInit('ww_ex24', 'Examples', layout)
   COMMON draw, img
   LOADCT, 5, /SILENT
   img = BYTARR(512,512)
   OPENR,1, !Data_Dir + 'head.img'
   READU,1,img
   CLOSE, 1
   draw = WwDrawing(layout, 1, 'DrawCB', [256,256], [512,512])
   status = WwSetValue(top, /Display)
   WwLoop
END

See Also

For detailed information on GUI development, refer to the PV‑WAVE Application Developer’s Guide.

For more information about how to write an application program based on PV‑WAVE Widgets, refer to Using Wave Widgets in the PV‑WAVE Application Developer’s Guide.

For additional information on the color and font keywords, see "Setting Colors and Fonts" in the PV‑WAVE Application Developer’s Guide.

For additional information on attachment keywords, see "Form Layout: Attachments" in the PV‑WAVE Application Developer’s Guide.

For information on Get and Set values, see "Setting and Getting Widget Values" in the PV‑WAVE Application Developer’s Guide.