WwInit Function
Initializes the PV‑WAVE Widgets environment, opens the display, creates the first top-level shell, and creates a layout widget.
note | The WwInit function should only be used in the main event loop. Do not use it to create an event loop within an event loop. PV‑WAVE could become unstable. To create additional main windows, use the WwMainWindow command instead of a secondary event loop. |
Usage
topshell = WwInit(app_name, appclass_name, workarea[, destroyCallback])
Input Parameters
app_name — A string containing the name of the application. This name can be referenced in a resource file.
appclass_name — A string containing the application class name, which can be the name of a resource file.
destroyCallback — (optional) A string containing the name of the callback that is executed when the top-level shell is destroyed.
Output Parameters
workarea — The widget ID of the layout widget that is created inside of the top-level shell.
Returned Value
topshell — The widget ID of the top-level application shell.
Keywords
Board — If present and nonzero, a bulletin board layout is created inside the top-level shell.
Border — Specifies the width in pixels of the borders for the layout widget and its child widgets. Default is 0.
Colors — (Motif only) The maximum number of color table indices to be used. Otherwise, PV‑WAVE uses all of the available color indices.
ConfirmClose — A string containing the name of the procedure called when the user selects the Close or Quit menu button from the window manager menu.
Form — If present and nonzero, a form layout is created inside the top-level shell.
Height — An integer specifying the height (in pixels) of the top level widget.
Horizontal — If present and nonzero, orients child widgets horizontally within the layout widget (the default). Used with row/column layouts only. For more information on layout widgets, see the WwLayout Function.
Icon_file — A string containing either the full pathname or the filename of the icon file. If the icon file is not found, then the warning message, "Unable to find specified icon file: filename, using default icon file." appears.
note | The default icon definition is based on Windows vs. Motif as the window manager. On Windows, the default becomes the parent icon definition or the system icon if no parent has defined a unique window icon. On Motif, the default becomes the icon defined by !WIDGET_ICON. |
Layout_name — Specifies the name of the layout widget. The Layout_name specified is part of the resource specification. The default for Layout_name depends on other keywords specified in the WwInit usage.
If either Board or Form are specified, the Layout_name default is layout.If either Horizontal or Vertical are specified, the default for Layout_name is workarea.Position — Specifies the position of the upper-left corner of the main window on the screen.
Resource — Specifies a particular resource file to load into the resource manager database. The resources in the file can be used to set attributes of the top-level shell created by WwInit. The defaults are:
(UNIX) <wavedir>/bin/Wave.ad
(WIN) <wavedir>\bin\Wave.ad
Where <wavedir> is the main PV‑WAVE directory.
Shell_name — Specifies the name of the TopLevelShell widget. The Shell_name specified is the top-level widget shell name used as part of the resource specification. (Default: application_name.)
Spacing — Specifies the amount of space between child widgets inside the layout. Used with row/column layouts only. Default is 0. For more information on layout widgets, see the WwLayout Function.
Title — A string specifying a title for the shell.
UserData — A variable. If the ConfirmClose keyword is specified, the value of this variable is passed to the Close or Quit callback procedure.
Vertical — If present and nonzero, orients child widgets vertically within the layout widget. Used with row/column layouts only. For more information on layout widgets, see the WwLayout Function.
Width — An integer specifying the width (in pixels) of the top level widget.
Color/Font Keywords
Background — Specifies the default background color name for an application.
Font — Specifies the name of the default font used for text in an application.
MSFont — Adds support for Windows fonts.
Foreground — Specifies the default foreground color name for an application.
Discussion
Call this routine before the first use of a PV‑WAVE Widgets routine.
The ConfirmClose keyword lets you control what happens when the user selects Close or Quit from the window manager menu. Normally, the window from which the menu item was selected is destroyed; however, you might want to display a confirmation dialog box or take another action instead of simply allowing the window to be destroyed. The callback procedure specified by ConfirmClose destroys the window when appropriate.
The ConfirmClose procedure you specify accepts two parameters: wid and user_data, where:
wid — The widget ID of the top-level shell of the application.user_data — The variable specified via the User_Data keyword. If User_Data is not specified, 0 (zero) is passed to the ConfirmClose routine.If specified, your ConfirmClose routine must close the top-level shell of the application. An example of a simple ConfirmClose routine which just closes the shell is:
PRO MyConfirmClose, wid, user_data
s = WwSetValue(wid, /Close)
END
If ConfirmClose is not specified, then the shell is closed.
Example
For examples showing the use of WwInit, see any of the PV‑WAVE Widgets widget-creation routines, such as WwButtonBox Function, WwCommand Function, WwControlsBox Function, WwList Function, and so forth.
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.
