WMMenu Programming Library

Introduction
Remote Process Event Handling
Compiling and Linking
Release Notes
Function call reference list

Introduction

The Widget Menu Library is a set of GUI convenience routines written for the IVE package. WML is Motif based and uses events and callbacks to control the flow of user input into your program. The library provides the tools to create menus with a variety of different user input items (widgets ), and establishes an event link between the user and IWL monitors. One more feature of the library is an Information widget which allows for context sensitive help.

The steps to needed to create a menu are:

Initialize the menu with WMInit.
Add widgets.
Display the menu with WMDisplay.
Use WMAppMainLoop or WMProcEvent to get events

Example Program: Hello World

#include "WMInclude.h"
#include <stdlib.h>    /* exit */

int end_program()
{
    exit(0);
    return 0;
}


int main(int argc, char* argv[])
{
    int maxlen = 12;
    int group = 1;

    WMInit("Hello World Demo");
    WMAddText("Hello World", maxlen, group);
    WMAddFuncButton("quit", end_program, NULL, 0, 0);
    WMDisplay();
    WMAppMainLoop();
    return 1;
}

This program creates a menu, containing a text widget that says "Hello World". Next to the Text Widget is a quit button. The menu will remain on the screen until the quit button is pushed, then the end_program routine will be called and the program ends.

I. Menu creation

A call to WMInit creates the first menu. Other submenus may be created in the same program by calling WMInitSubMenu. Optional calls which affect the behavior of WMInit and WMInitSubMenu are:

WMSetLoc: Sets the position of the menu on the screen.
WMNoTitleBar: Causes the all subsequent menus without titles to be created without title bars.
WMOverrideRedirect: Causes the next menu created to pop up (as a warning or error dialog would) even if the user has instructed the window manager to cause interactive placement of normal menus.
WMSetOverlayUse: Sets whether or not dialogs or pulldowns should be put in the overlay planes.

II. Widget creation

A. Adding Widgets

All of the functions, with the prefix WMAdd, add a new widget to the current menu and return a widget index. The widget index can be referenced later for updates to that widget. The types of widgets that are provided in the widget set include input fields, output fields, selection, function buttons and drawing areas. An example will be provided below for the use of each type. Each Widget function has a set of parameters unique to that widget but there are several parameters that most of the widgets share in common. These general parameters are described here.

First of all, many widgets are associated with some variable or variables. In the input field example below, the first parameter requires the address of the variable it will represent. The second variable tells how many variables the first parameter refers to, ie. whether it is a single variable or an array. In this case the Widget will display a single floating point variable which is initially 5.9. The user will be able to enter a different number into this widget and the variable will be changed.

The next parameter common to most widgets is the callback. This will be the name of the function that should be called whenever a user enters something into this widget. If you do not wish to call any function when this widget is changed simply enter NULL for this parameter. The parameter immediately following the callback, is the parameters to pass to the callback. Obviously if the callback is NULL, the params should be NULL as well. But if you do have a callback function and want to pass parameters to it, remember this. You can pass just one integer pointer to the callback. If you only want to pass one integer, that's ok, but cast it as an integer pointer. Otherwise you can pass the address of any variable type, pass an array of variables, or organize multiple variables into a structure and pass its address. Functions used as callbacks must always be of type integer.

The third pair of variables used by most widgets has to do with grouping. In the input field example, update and group are the variables involved. The Widgets can be put into groups such that you can disable or update all the widgets in one group with a single call. Widgets are attached to a group by entering an integer number in the group parameter. Grouping is done using binary masking meaning....

group computer sees 1 00001 2 00010 4 00100 ..........etc.

To keep the groups independent of each other, it is best to number them in powers of 2: 1,2,4,8... For example, if you give a command to update group 3(00011). Groups 1 and 2 will both be updated since the one's and the two's positions each are true in binary. This can be used to your advantage to group and subgroup. You can also avoid the grouping thing entirely by putting a zero in the group field.

The update field can be set to zero or one. If it is set to one, then any time the widget is changed by the user, after its callback has been executed, if any variables of other widgets in the same group have been changed, those widgets will be updated to reflect the new value.

Example I

#include "WMInclude.h"
#include <stdio.h>   /* sprintf */
#include <stdlib.h>  /* exit */

static char result_string[20] = "0.0000";

int end_program()
{
    exit(0);
    return 0;
}


int update_square(float *fvar)
{
    float value = *fvar;
    float result = value * value;

    sprintf(result_string, "%f", result);
}


int main(int argc, char* argv[])
{
    float fvar = 0.0;
    int maxlen = 10;
    int dislen = 12;
    int decimal = 2;
    float min = 0;
    float max = 0;

    WMInit("Squares Program");
    WMAddInfoButton("Input:", NULL);
    WMAddFloatField(
        &fvar, 1, dislen, maxlen, &min, &max, &decimal, update_square, (int*) &fvar, 1, 2
    );
    WMNewRow();
    WMAddInfoButton("Result", NULL);
    WMAddText(result_string, dislen, 2);
    WMNewRow();
    WMAddFuncButton("quit", end_program, NULL, 0, 0);
    WMAttachRightSide();
    WMDisplay();
    WMAppMainLoop();
    return 1;
}

Example I demonstrates the use of input field, output field, and function button widgets along with the use of callbacks and group updating. The input field WMAddFloatField calls update_square when a user enters a value into it. Because the update field is set to 1, and the group number is 2, any other widget in group 2 will be automatically updated after the callback routine has been executed, the callback "update_square" calculates the square of the last value entered into the input field, and writes the result to the result_string which is reported by the control added by WMAddText. The user can keep entering input and getting results until the user presses the function button to quit. Then the function end_program is called and the program ends.

There are several different classes of widgets. Input fields allow users to type in information; the calls to create these fields are:

WMAddCharField: Holds a character string.
WMAddFloatField: Holds one or more floating point variables.
WMAddIntField: Holds one or more integer variables

Output fields report the current state to the user but do not accept input and do not have an associated callback routine. The calls to create output fields are:

WMAddOnOffStatus: Is an indicator light to show status
WMAddText: Shows one line of text.
WMAddScrolledText: Is a scrollable widget to show multiple lines of text.
WMAddStatusBar: Is a thermometer-style bar for showing how far along a process is.

Function buttons cause something to happen (generally whatever the registered callback function does). The calls to create function buttons are:

WMAddArrowButton: Creates a button labeled with an arrow symbol pointing in one of four directions.
WMAddDoButton: Creates a button which starts an external program when pressed.
WMAddFuncButton: Creates a button with a label; when pressed the button will cause the registered callback to be invoked.
WMAddFuncList: Shows a list of options to the user and calls the function associated with the option chosen.
WMAddInfoButton: Frequently used as a label; when pressed will display online help.
WMAddSaveButton: Creates two buttons. Pressing one saves the values of all the parameters associated with the widgets in the menu; the other restores the values that were previously saved.

Selection widgets are a grab bag of widgets. Some are similar in function to input fields, but generally do not require the input to be typed. Others are similar in function to lists of function buttons. The calls to create selection widgets are

WMAddGetFile: Creates a function button which will open a file selection dialog and an adjacent character field in which the last file selection is shown and which may be used to change the file selection directly.
WMAddHorSlider: Creates a horizontal slider bar.
WMAddOptionMenu: Creates a pulldown set of options; the last selection is displayed on top.
WMAddPulldown: Creates a single pulldown menu.
WMAddPulldownMenu: Creates a cascade of menus.
WMAddScrolledChoices: Creates a scrolled list of options which lets the user select an option by clicking on it.
WMAddToggleButton: Creates a toggle button which may be turned on or off by the user.

Drawing areas are blank canvases which can be used for customized drawing. The calls to create drawing ares are:

WMAddDrawingArea: Creates an area in your menu for drawing using X, Xt, and Motif library calls.
WMAddGLwMDrawWidget: Creates an area in your menu for drawing using OpenGL library calls.

B. Widget Modifications

Once widgets have been created, the programmer may need to control the conditions under which a user can input into the widgets. WMEnableField and WMDisableField do just that, enable and disable the widget for user input. The widget will dim slightly when its disabled WMEnableGroup and WMDisableGroup do the same thing only now one call effects all the widgets that belong to that group. WMUnpasteWidget and WMPasteWidget completely remove and restore (respectively) a widget from the menu.

The information that a widget shows a user may change and need updating. WMUpdateField and WMUpdateGroup when called will recheck the variables that are being looked at through a widget (or widgets) and update the widget(s) if the value is different from the currently displayed value. WMChangeText can be used to change the text on any widget that uses a string to write a label on the widget. These are toggle button, onoff status, function button, infobutton, dobutton. WMChangeTitle lets you change the title for the slider and the statusbar

If after you have already created your menu, you later want to insert a widget or delete a widget from the menu, you can do that with WMInsertWidget, WMEndInsert and WMDeleteWidget.

There are several modifications functions that are for a particular widget. These functions will be described in the Widget Section after the Widget it affects.

C. Widget Positioning

The first widget added to the menu will be in the top left hand corner. Widgets added after that are added to the right side of the previous widget. To start a new row of widgets, there is a call WMNewRow which puts the next widget after that against the left side of the menu and below the other widgets. So the general order of widget creation is left to right and top to bottom. There are two other calls that are used in positioning of widgets. WMSetOffset lets you specify the spacing between widgets. WMAttachRightSide extends the last widget created to the right side of the menu. Finally WMAddSeparator draws a horizontal line between two rows of widgets. Use it in place of WMNewRow if you want a line separating sections of the menu.

III. Menu Display

In order to see the menu that's been created you have to make a display call. WMDisplay will display the menu created by calling WMInit. WMDisplaySubMenu will display submenus created by WMInitSubMenu. WMUndisplaySubMenu will hide a menu again until the next time WMDisplaySubMenu is called. With multiple menus, the menus are numbered sequentially by order of creation, and this number is returned by WMInitSubMenu. You can hide the main menu by calling WMUndisplaySubMenu with an argument of zero.

IV. Processing Events

The menu system is based on the ability to process events from the user, since callbacks will only be called as a response to an event. There are two ways to handle events. WMAppMainLoop starts an event processing loop. Once started, the event loop will keep handling events until a function is called to exit the program. WMProcEvent provides a way to check for a single event. This is particularly useful when a program is doing some other type of looping and you need to check for user interrupt. Then once in every loop cycle, you can make this call to check for an event.

For controls created by WMAddArrowButton or WMAddFuncButton, you can get more information about the event that activated the button using WMRetLastButEvent or WMGetLastButNum.

V. Error and Info popups

There are several window pop ups available to display special information to the user about what is currently happening in the program. WMConfirm is used to check with the user if what the program is about to do is ok. The user can respond ok or cancel, and the function will return the response back to the program so you can respond accordingly. WMConfirmError pops up a message to the user letting them know that there is some error in what they are trying to do so they can do it correctly. WMPostInfo lets the program give some information to the user such as some task is done.

To have an application cause the help viewer to display a specific topic, use WMDisplayHelp.

VI. File Selection

There is a file selection menu that can be popped up directly by calling WMGetFile or pops up when a user hits the GetFile button created by a call to WMAddGetFile. This menu by default, will show the user the list of files in the users home directory, using the file filter *.dat. The user can change the file filter and directory in the menu and select the file they are looking for. In order to start with a directory and file filter other than the defaults, there is another call you can set in your program. WMSetGetFileSrc can be used to set a key to find the last directory and file filter the user used for file selection with your program. In each users home directory is a file called .ivestartup. (If there is not, there will be one after the first time they run Priism). This is an ASCII file containing a list of directory and filter keys associated with the last directory and filter used by the user when these keys were set. Every time a new set of keys is used, they will be added to the list. Every time the user runs the program they will start in the directory currently associated with the key in the file, and if they end with a different directory, .ivestartup will be updated with the new settings. You can create a different key name for every program or every type of file.

VII. Monitor event handling

WMMenu provides a way for your program to keep track of user interaction with the IVE monitor. This allows your program to handle tasks such as data picking and region selection in the image as well as updating information based on the changing state of the monitor.

You must use WMEnableIWLEvent before any of the following events can be sent from the monitor to your program. In case that you wish to stop receiving events from the monitor, use WMDisableIWLEvent.

For events such as change in zoom, section, image shift, resize, expose etc. use WMProcDisplayChange to associate a callback routine with the event. Use WMCancelDisplayChange when you no longer need this type of event. **we need to look into some constants for the different kinds of display changes

For events such as mouse actions in the window, and keypress events use WMAddEventHandler and use WMCancelEventHandler when you no longer need this kind of event.

VIII. Remote Process Event Handling

This set of calls lets you run and communicate with a remote program from an interactive session. This provides a way to make use of faster machines for data processing while viewing results on a machine that can display the images with IVE. The remote program can use regular imsubs calls to read and write to your image windows. See the documentation for IMOpen in IM_ref2.html for a description of using imsubs from a remote program.

In order for communication to work, both the session side program and remote program must call WMInit to initialize the event handling. The session side program starts up the remote program using the call WMStartRemoteProgram. After all callbacks are set up on both sides, WMProcEvent or WMAppMainLoop can be used to get the input events.

Callbacks are setup using the function WMAddInputEventHandler. Both the session program (prog1) and the remote program (prog2) can set up callback functions to receive information from the other side. Each WMAddInputEventHandler call registers a different function to be called upon receipt of an input event and associates the function with a reference id. A program can set up as many callback functions as it needs. Prog1 needs to know the prog2 reference ids and vice versa so that they can use these ids to specify which function the data is intended for.

WMRemoteSendData is used to send the data to the other side using the reference id. Any number, except zero, may be used as a reference id, by WMAddInputEventHandler. Zero may be used as the reference id by WMRemoteSendData when data is being sent synchronously. In this case, the receiving program should be waiting for the data with a WMRemoteGetInt2, WMRemoteGetInt4 or WMRemoteGetBytes call, instead of waiting for the next input event.

Functions called by the event handler, will receive as a parameter the number of bytes that are being sent to this function. The function should know what kind of data it is receiving, ie integers, reals, character data. The function will then get the data using the calls WMRemoteGetInt2, WMRemoteGetInt4 and WMRemoteGetBytes as appropriate.

Compiling and Linking

Programs written in C/C++ which use the WM functions should include WMInclude.h to provide prototypes and define structures and macros used with the WM functions. For programs written in Fortran, WM.inc defines the WM_* and key symbol constants.

When linking your application, link against libWM.a or libWM.so (libWM.dylib on Mac OS X).

Platform Specifics

IRIX

In IVE versions since 3.3, the WM library is in the n32 object format. Therefore you will need to compile and link your application so that it is in the n32 format as well. Supplying the -n32 option to the compiler and linker is one way to do this; see the pe_environ (5) man page for others.

The headers are located in the IRIX/INCLUDE directory and the libraries are in the IRIX/LIB directory of the Priism distribution. If you use the archive library, libWM.a, it is necessary to also link against the libraries used internally by the WM library. The additional options needed when linking are:

    -lIWL -live -lGLw -lXm -lXt -lX11 -lGL

(the IWL and ive libraries are in the same directory as the WM library; the others are standard system components).

x86 Linux

To use the x86 Linux library, you will need an x86 Linux system that supports compiling ELF executables, has glibc2.1, and has the X, OpenGL (or Mesa) libraries and headers installed.

The headers are located in the Linux/x86/INCLUDE directory of the Priism distribution. For C/C++ programs, including WMInclude.h has the side effect of including X and OpenGL headers; if the path to those headers is not in the default search path then it will be necessary to include it in the search path (in most cases, adding

    -I/usr/X11R6/include

to the compilation options will do this).

The library is located in the Linux/x86/LIB directory of the Priism distribution. If you link against libWM.so, it is necessary to instruct the linker to search Linux/x86/LIB and lesstif/Linux/x86/lib for libraries that libWM.so uses. If you invoke the linker directly, this can be done by adding

    -rpath-link install_dir/Linux/x86/LIB -rpath-link install_dir/lesstif/Linux/x86/lib

to the linker options (replace install_dir with the path to the Priism distribution). If the compiler is used to invoke the linker, then you will need to determine how to instruct the compiler to pass the above option to the linker; for most compilers it can be done with

    -Wl,-rpath-link,install_dir/Linux/x86/LIB -Wl,-rpath-link,install_dir/lesstif/Linux/x86/lib

libWM.so also depends on the X and OpenGL libraries; if the paths to those libraries are not in the directory search path, it will be necessary to supply additional -rpath-link options.

If you use the archive library, libWM.a, it is necessary to link against the libraries that those libraries use. For libWM.a, these additional libraries can be specified on the command line as

    -lIWL -live -lGLw -lXm -lXt -lX11 -lGL

(the IWL, ive, and GLw libraries are in the same directory as the WM library; the Xm library can be found in lesstif/Linux/x86/lib within the Priism directories; the others are assumed to be in the default search path; if they are not it will be necessary to add them).

x86_64 Linux

To use the x86_64 Linux library, you will need an x86_64 Linux system that has glibc2.3, and has the X, OpenGL (or Mesa) libraries and headers installed.

The headers are located in the Linux/x86_64/INCLUDE directory of the Priism distribution. For C/C++ programs, including WMInclude.h has the side effect of including X and OpenGL headers; if the path to those headers is not in the default search path then it will be necessary to include it in the search path (in most cases, adding

    -I/usr/X11R6/include

to the compilation options will do this).

The library is located in the Linux/x86_64/LIB directory of the Priism distribution. If you link against libWM.so, it is necessary to instruct the linker to search Linux/x86_64/LIB and lesstif/Linux/x86_64/lib for libraries that libWM.so uses. If you invoke the linker directly, this can be done by adding

    -rpath-link install_dir/Linux/x86_64/LIB -rpath-link install_dir/lesstif/Linux/x86_64/lib

    -Wl,-rpath-link,install_dir/Linux/x86_64/LIB -Wl,-rpath-link,install_dir/lesstif/Linux/x86_64/lib

libWM.so also depends on the X and OpenGL libraries; if the paths to those libraries are not in the directory search path, it will be necessary to supply additional -rpath-link options.

If you use the archive library, libWM.a, it is necessary to link against the libraries that those libraries use. For libWM.a, these additional libraries can be specified on the command line as

    -lIWL -live -lGLw -lXm -lXt -lX11 -lGL

(the IWL, ive, and GLw libraries are in the same directory as the WM library; the Xm library can be found in lesstif/Linux/x86_64/lib within the Priism directories; the others are assumed to be in the default search path; if they are not it will be necessary to add them).

Mac OS X

To use the WM library on Mac OS X, it is necessary to have the X and OpenGL (or Mesa) libraries and header files installed. For Apple's X11, the X and OpenGL libraries are included; the header files are part of a separate component, the X11 for Mac OS X SDK. The XDarwin binaries have the X and OpenGL libraries and header files.

The WM header files are located in the Darwin/INCLUDE directory of the Priism distribution. For C/C++ programs, including WMInclude.h has the side effect of including X and OpenGL headers; if the path to those headers is not in the default search path than it will be necessary to include it in the search path (in most cases, adding

    -I/usr/X11R6/include

to the compilation options will do this).

The WM libraries are located in the Darwin/LIB directory of the Priism distribution. Because of the way libWM.dylib was built, it is necessary to mention some of the libraries libWM.dylib depends upon when linking with libWM.dylib. One way to do so is to include the following after in the command-line options when linking:

    -lIWL -live -lGLw -Linstall_dir/lesstif/Darwin/lib -lXm

where you would replace install_dir with the path to where Priism is installed. The above method has the slight disadvantage that your application will have an explicit dependence on those additional libraries; an alternative method which avoids the explicit dependencies at the expense of more involved command-line options is used in the sample Makefile for Priism applications.

If you use libWM.a, it is necessary to link with all the libraries necessary for libWM.dylib and also libXt, libX11, and libGL, i.e. add

    -lIWL -live -lGLw -Linstall_dir/lesstif/Darwin/lib -lXm -Lxpath -lXt -lX11 -lGL

to the link options. In the above expression, replace xpath with the path the X11 libraries and OpenGL library for X11; with Apple's X11 or XDarwin, xpath is /usr/X11R6/lib.

Release Notes

The following changes break backward compatibility between IVE 4 and IVE 3.3:

The handling of Widget return values and arguments in the Fortran interface changed in Priism 4.2.0. The change will be transparent except for the case where you pass Widget values between C/C++ and Fortran on 64-bit systems. The solution, which can be used either on 32-bit or 64-bit systems is to use IVEFtnIdToPtr to convert a Fortran integer to a Widget value and IVEPtrToFtnId to convert a Widget value to a Fortran integer.
In 4.1.9, changed the value of the WM_RIGHT_ARROW and WM_LEFT_ARROW constants for Fortran.
The handling of shell widgets changed in Priism 4.1.4. The primary effects are:
- All shells created with WMInit, WMInitSubMenu, or WMGetShellWidget are now created with XtCreatePopupShell rather than XtAppCreateShell. Code that pops up one of these shells with XtRealizeWidget should be modified to use WMDisplay, WMDisplaySubMenu, or XtPopup instead. Code that pops down one of these shells with XtUnrealizeWidget should be modified to use WMUndisplaySubMenu or XtPopdown instead.
- An undocumented feature allowed multiple functions to be registered with WMSetExitFunction; now only the last function registered with WMSetExitFunction has an effect. Another undocumented feature passed the shell widget, the Display pointer (as an XtPointer), and another XtPointer as arguments to the callback. Now nothing is passed. Both changes make WMSetExitFunction behave like WMSetSubExitFunc.
- Adding your own handler for the WM_DELETE_WINDOW protocol with XmAddWMProtocolCallback (or equivalent) on the shell returned by WMInit is not guaranteed to work: the order of callbacks is not specified by Xt and the callback added by the WM library forces the program to exit. Use WMSetExitFunction instead.
- File dialogs popped up by WMAddGetFile controls are now created as children of the push button. That, in turn, required a modification to the Priism FAQ's procedure for adjusting fonts.
Certain functions and data items, which were visible in the library but not mentioned in the documentation or header files, were removed in 4.1.2. The functions removed were add_item, clear_rec_data, create_and_run_remote_command_script, get_char_attr, get_float, get_float_attr, get_int, get_ive_def, get_long_attr, get_parm, get_rec, get_text, hide, init_GL_widget, put_char_attr, put_float_attr, put_long_attr, save_ive_def, set_wm_switch_format (renamed to wm_set_switch_format), skip_line, and wr_res. The data items removed were form, form1, Head, hold_form, hold_left, hold_top, hold_xstart, left, top, and xstart.
When a file was successfully selected with WMGetFile (the function returned 1), IVE 3.3 and previous versions had the undocumented side effect that the contents of the string passed as the second argument to WMGetFile were copied (via strcpy) to the fourth argument. That is no longer the case; the second, third, and fourth arguments of WMGetFile are not examined or used in any way. This change was introduced in 4.0.7.
The following functions, declared in WMFunc.h in previous versions but apparently only used internally within the library, are no longer available: strip_spaces, WM_choices_callback, WMadditem, WMarrowcallback, WMattachtoform, WMbutcallback, WMcancel, WMcancelreadfile, WMdecodeforstring, WMdragcallback, WMexecbut, WMflcallback, WMfixforstring, WMgetfile, WMgetfloats, WMgethelp, WMgetints, WMgetstring, WMgettimeout, WMhelpcallback, WMinsensitive, WMpcallback, WMreadfile, WMrestore, WMretfilename, WMsave, WMsavedefdirpat, WMscallback, WMsensitive, WMstopproc, WMtogglefunc, and WMupdatefield.
The following functions, which were not mentioned in WM header but which were visible in the library, are no longer accessible: CopyScale, determine_switch_format, GetDefDirPat, getfilename, and SaveDefDirPat. The following data items, which were not mentioned in a WM header but which were visible in the library are no longer accessible: app_file, buf, note_f, and res_dir.
Including WMInclude.h no longer has the side effect of include Xm/Xm.h.
The locations of the headers and libraries has changed. In previous versions, the headers were in the INCLUDE subdirectory and the libraries were in the LIB (or LIB_IRIX) subdirectory for IRIX.
libWM.a was called WM.a. The old name is still available as symbolic link to the new one but may be removed in a future release.

Additions to the library in IVE 4 are:

Added the function WMDisplayHelp. It may be a satisfactory replacement for applications which previously called WMhelpcallback.
In 4.0.7, added the functions WMGetMenuSize and WMGetScreenSize.
In 4.0.10, extended WMRegMouseButton and WMUnRegMouseButton to handle buttons 4 and 5 (often mapped to the scroll wheel on mice which have one).
In 4.1.3, added WMChangeScrolledChoicesSelection.
In 4.2.0, added WMGetPulldownShowChoice and Fortran interfaces for XtParent, WMAddNestedPulldown, WMAddPullRight, WMAddPulldownMenu, WMChangePulldown, WMDeleteWidget, WMEndInsert, WMInsertWidget, WMSetExitFunction, and WMSetSubExitFunc.

Changes made to both IVE 4 and IVE 3.3:

In IVE 4.1.6 and the November 2003 release of IVE 3.3, modified WMAddIntField and WMAddFloatField to dynamically determine the length needed rather than relying on their maximum length argument.

Changes made in IVE 3.3 were:

The October 1999 release included modifications to WMConfirm, WMConfirmError, WMPostInfo, and WMShowInfo to support messages with multiple lines.
The June 1999 release included modifications to WMAddNestedPulldown and WMAddPullRight to support insertion of separators.
The January 1999 release added the calls WMSetOverlayUse and WMOverlayDepth.
The October 1998 release added the WMGetLoc call; the return type and arguments for that call were modified for the October 1999 release.

Function Calls By Category

Menu Creation

WMInit
WMInitSubMenu
WMNoTitleBar
WMOverrideRedirect
WMSetLoc
WMSetOverlayUse

Widgets

WMAddArrowButton                   WMAddOptionMenu
WMAddCharField                     WMAddNestedPulldown
WMAddDoButton                      WMAddPullRight
WMAddDrawingArea                   WMAddPulldown
WMAddFloatField                    WMSetPulldownShowChoice
WMAddFuncButton                    WMGetPulldownShowChoice
WMAddFuncList                      WMAddPulldownMenu
WMAddGetFile                       WMAddSaveButton
WMAddGLwMDrawWidget                WMAddScrolledChoices
WMAddHorSlider                     WMAddScrolledText
WMSliderShowValue                  WMAddSeparator
WMAddInfoButton                    WMAddStatusBar
WMAddIntField                      WMAddText
WMAddOnOffStatus                   WMAddToggleButton

Widget Modification

WMDisableField                     WMUpdateField
WMEnableField                      WMChangePulldown
WMDisableGroup                     WMChangeScrolledChoicesSelection
WMEnableGroup                      WMChangeText
WMUnpasteWidget                    WMChangeTitle
WMPasteWidget                      WMInsertWidget
WMSensitiveGroup                   WMEndInsert
WMInsensitiveGroup                 WMDeleteWidget
WMUpdateGroup

Widget Positioning

WMAttachRightSide
WMNewRow
WMSetOffset

Menu Display

WMDisplay
WMDisplaySubMenu
WMUndisplaySubMenu

Processing Events

WMAppMainLoop                      WMGetLastButNum
WMProcEvent                        WMRetLastButEvent

Error and Info Popups

WMConfirm                          WMShowInfo
WMConfirmError                     WMRemoveInfo
WMPostInfo                         WMDisplayHelp
WMRingBell

File Selection

WMGetFile
WMSetGetFileSrc

Monitor Event Handling

WMEnableIWLEvent                   WMCancelEventHandler
WMDisableIWLEvent                  WMProcDisplayChange
WMAddEventHandler                  WMCancelDisplayChange
WMRegMouseButton                   WMUnRegMouseButton

Remote Process Event Handling

WMStartRemoteProgram               WMRemoteSendData
WMAddInputEventHandler             WMRemoteGetBytes
WMCancelInputEventHandler          WMRemoteGetInt2
WMRemoteGetInt4

Window Manager Control

WMSetExitFunction
WMSetSubExitFunc

Display/Dialog/Widget Information

WMGetLoc                           WMGetMenuSize
WMGetScreenSize                    WMOverlayDepth

Menu Creation Functions

WMInit

Overview

Initializes the WM library if necessary and creates the container (a Motif form widget) for the main dialog window. This function must be called before creating other user interface controls. Calling WMInit more than once from a program will lead to undefined behavior.

C Prototype

#include "WMInclude.h"
Widget WMInit(const char* title);

Fortran Prototype

integer function WMInit(title)
character*(*) title

Parameters

title: (in) Is the title to display on the main dialog window. If title is a null pointer (or, in Fortran, if title is all spaces or the first character of title is a null character) and WMNoTitleBar has been called, the window manager will be instructed to only display resize handles on the main dialog. If you use the Fortran interface and want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, title must include a null character (i.e. char(0)) to mark the end of the title when title is not a null pointer.

Return Value

Returns an identification value for the container created.

WMInitSubMenu

Overview

Initializes the WM library if necessary and creates the container for a child dialog window. If an insertion initiated with WMInsertWidget is still active, the call to WMInitSubMenu implicitly terminates the insertion as if you had explicitly called WMEndInsert with an argument of one.

C Prototype

#include "WMInclude.h"
int WMInitSubMenu(const char* title);

Fortran Prototype

integer function WMInitSubMenu(title)
character*(*) title

Parameters

title: (in) Is the title to display on the child dialog window. If title is a null pointer (or, in Fortran, if title is all spaces or the first character of title is a null character) and WMNoTitleBar has been called, the window manager will be instructed to only display resize handles on the dialog. If you use the Fortran interface and want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, title must include a null character (i.e. char(0)) to mark the end of the title when title is not a null pointer.

Return Value

Returns the zero-based index of the dialog created. You can use this index with WMDisplaySubMenu or WMUndisplaySubMenu.

WMNoTitleBar

Overview

If you call WMNoTitleBar, all subsequent calls to WMInit and WMInitSubMenu will instruct the window manager to only display resize handles on the dialog when a null pointer (or, in Fortran, a character array containing all spaces or which has a null character as the first element) is passed for the dialog title.

C Prototype

#include "WMInclude.h"
int WMNoTitleBar(void);

Fortran Prototype

integer function WMNoTitleBar()

Return Value

Returns zero.

WMOverrideRedirect

Overview

WMOverrideRedirect turns on or off window manager intervention when dialogs are displayed with WMDisplay or WMDisplaySubMenu. Normally when you display a dialog, the window manager is responsible for positioning and decorating the dialog. You may not want that behavior for some types of dialogs (a dialog which emulates a popup menu, for instance); you would then call WMOverrideRedirect(1) before displaying the dialog and call WMOverrideRedirect(0) to restore the default behavior after the dialog has been displayed.

C Prototype

#include "WMInclude.h"
int WMOverrideRedirect(int flag);

Fortran Prototype

integer function WMOverrideRedirect(flag)
integer flag

Parameters

flag: (in) If flag is not zero, subsequent calls to WMInit or WMInitSubMenu will create dialogs that are displayed without window manager intervention. If flag is zero, subsequent calls to the WMInit or WMInitSubMenu will create dialogs that will be decorated and positioned by the window manager.

Return Value

Returns zero.

WMSetLoc

Overview

Sets the screen location for the dialog created by the latest call to a WMInit or WMInitSubMenu. To accommodate different screen sizes, it is best to determine the size of the screen (WMGetScreenSize will do this for the default screen) and use that as a basis for the location.

C Prototype

#include "WMInclude.h"
int WMSetLoc(int x, int y);

Fortran Prototype

integer function WMSetLoc(x, y)
integer x, y

Parameters

x: (in) Is the position, in pixels, of the left edge of the dialog. A value of zero is equivalent to the left edge of the screen; positive values shift of x shift the dialog to the right from the left of the screen.
y: (in) Is the position, in pixels, of the top edge of the dialog. A value of zero is equivalent to the top edge of the screen; positive values shift of y shift the dialog downward from the top of the screen.

Return Value

Returns negative one and has no effect if x or y is less than zero; otherwise, returns zero.

WMSetOverlayUse

Overview

What is visible on the screen consists of one or more layers, depending on the graphics hardware and drivers. A layer can be updated independently without affecting the contents of the other layers. The overlay planes are a layer whose contents can obscure the contents of the layers normally used for drawing. The overlay planes are especially useful for drawing on top of windows that are time-consuming to redraw. A disadvantage of the overlay planes is that they may have a limited number of available colors.

Use WMSetOverlayUse to control whether or not dialogs or pulldown menus created after the call to WMSetOverlayUse will attempt to use the overlay planes. To test whether or not overlay planes are available and the number of colors in the overlay planes, you can use WMOverlayDepth.

This function was added in January 1999.

C Prototype

#include "WMInclude.h"
int WMSetOverlayUse(int flag);

Fortran Prototype

include 'WM.inc'
integer function WMSetOverlayUse(flag)
integer flag

Parameters

flag: (in) If flag is equal to WM_OVERLAY_YES, subsequent calls (until the next call to WMSetOverlayUse) to WMInit, WMInitSubMenu, WMConfirm, WMConfirmError, WMShowInfo, WMPostInfo, WMAddOptionMenu, WMAddPulldown, WMAddPulldownMenu, WMAddNestedPulldown, WMAddPullRight will attempt to use the overlay planes (if the system does not support overlay planes the listed functions will operate normally). If flag is WM_OVERLAY_NO (or any other value not equal to WM_OVERLAY_YES), calls to create dialogs and pulldown menus will function normally: pulldowns will use the same planes as their parent dialogs and dialogs will use the normal planes.

Return Value

If WMSetOverlayUse has been called before, returns WM_OVERLAY_YES if the argument to the last call to WMSetOverlayUse was WM_OVERLAY_YES and returns WM_OVERLAY_NO if the argument to the last call to WMSetOverlayUse was something other than WM_OVERLAY_YES. Otherwise, returns WM_OVERLAY_NO.

Widgets Creation Functions

WMAddArrowButton

Overview

Creates a button labeled with a picture of an arrow (pointing up, down, left, or right). When the user presses the button, a routine registered by the user will be called.

C Prototype

#include "WMInclude.h"
Widget WMAddArrowButton(int dir, int (*callback)(), int* param);

Fortran Prototype

include 'WM.inc'
integer function WMAddArrowButton(dir, callback, param)
integer dir, callback, param
external callback

Parameters

dir: (in) Sets the direction of the arrow shown on the button. Possible values are WM_UP_ARROW, WM_DOWN_ARROW, WM_RIGHT_ARROW, and WM_LEFT_ARROW.
callback: (in) After the user presses the button, the WM library will call callback. The WM library will pass callback a single argument, the value of param (i.e. a pointer to an integer in C and a reference to an integer in Fortran), and will expect callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddArrowButton is called from C, callback may be zero to signal that no callback should be performed by the WM library when the button is pressed.
param: (in) Is passed as the argument to callback when the user presses the arrow button.

Return Value

Returns an identification value for the button created.

WMAddCharField

Overview

Creates a field which will display a single line of text that the user can modify.

C Prototype

#include "WMInclude.h"
Widget WMAddCharField(char* text, int maxlen, int dislen, int (*callback)(), int* params, int update, int group);

Fortran Prototype

integer function WMAddCharField(text, maxlen, dislen, callback, params, update, group)
character*(*) text
integer maxlen, dislen, callback, params, update, group
external callback

Parameters

text: (in/out) Is the storage for the text displayed in the field. If you call WMAddCharField from C or C++, text should be a null-terminated string capable of holding at least maxlen characters (including the terminating null character). If you call WMAddCharField from Fortran, text should be a character array, and, if you want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, text must include a null character (i.e. char(0)) to mark the end of the text.
maxlen: (in) Is the maximum number of characters text can hold. If WMAddCharField is called from C or C++, maxlen should include the space needed for the terminating null. If WMAddCharField is called from Fortran, WMAddCharField will use the smaller of maxlen and the maximum length of text as the maximum number of characters to store in text.
dislen: (in) Is the number of characters from text to display at one time.
callback: (in) When the user finishes editing the contents of the field (either explicitly by pressing Return when the field has input focus or implicitly by causing the field to lose input focus) and the contents of the field have changed since the later of the last edit or the last program-initiated update (via one of the WMUpdate routines), the WM library will call callback. The WM library will pass callback a single argument, the value of params (i.e. a pointer to an integer in C and a reference to an integer in Fortran), and will expect callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddCharField is called from C, callback may be zero to signal that no callback should be performed by the WM library when the user edits the text field.
params: (in) Is passed as the argument to callback.
update: (in) If update is nonzero and the user finishes an edit that modifies the contents of the text field, the WM library will call WMUpdateGroup with the value of group as the argument. If update is zero, the WM library will not call WMUpdateGroup internally when a change occurs.
group: (in) Is a bit mask for the group or groups to which the field will belong.

Return Value

Returns an identification value for the field created.

WMAddDoButton

Overview

Creates a push button, labeled "Do it", that when pushed will generate a script. The library will then execute the script via the command given by qcom. Until the command completes, the button will be labeled "Cancel", and pressing the button will open a confirmation dialog for the user to indicate whether or not to kill the running command.

C Prototype

#include "WMInclude.h"
Widget WMAddDoButton(int (*build_com)(), int* param, const char* qcom, char* command);

Fortran Prototype

integer function WMAddDoButton(build_com, param, qcom, command)
integer build_com, param
character*(*) qcom, command
external build_com

Parameters

build_com: (in) Is the routine the library will call to generate the script. The library passes the routine two arguments and expects an integer return value. The first argument is the value of param (i.e. a pointer to an integer in C and a reference to an integer in Fortran). The second argument is the value of command, the name of the script file (represented as a pointer to a character in C and a character*(*) array in Fortran). If the returned value is greater than or equal to zero, the WM library will proceed to operate upon the script as described in the overview of WMAddButton. Otherwise, the library does nothing with the generated script. When WMAddDoButton is called from C, build_com may be zero; in that case, the WM library will not call user code before executing the script.
param: (in) Is passed as the first argument to build_com.
qcom: (in) If qcom does not equal "NULL", qcom holds the command line to use when executing the script. A space and then the name of the script is appended to this command line before execution. If qcom is "NULL", the script is executed directly. If you call WMAddDoButton from Fortran and you want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, qcom must include a null character (i.e. char(0)) to mark the end of the command line.
command: (in) Is the name of the script file. If you call WMAddDoButton from Fortran and you want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, command must include a null character (i.e. char(0)) to mark the end of the file name.

Return Value

Returns an identification value for the button created.

WMAddDrawingArea

Overview

Creates a canvas (an instance of an XmDrawingArea) where you can do custom drawing via direct calls to the X libraries.

C Prototype

#include "WMInclude.h"
Widget WMAddDrawingArea(int width, int height);

Fortran Prototype

No Fortran interface is available.

Parameters

width: (in) Is the width, in pixels, of the drawing area.
height: (in) Is the height, in pixels, of the drawing area.

Return Value

Returns an identification value for the drawing area created.

WMAddFloatField

Overview

Creates a field which will display one or more floating-point values that the user can modify.

C Prototype

#include "WMInclude.h"

Widget WMAddFloatField(float* fptr, int num, int dislen, int maxlen, float* min, float* max, int* decimal, int (*callback)(), int* param, int update, int group);

Fortran Prototype

integer function WMAddFloatField(fptr, num, dislen, maxlen, min, max, decimal, callback, param, update, group)
integer num, dislen, maxlen, decimal, callback, param, update, group
real fptr(num), min, max
external callback

Parameters

fptr: (in/out) Is the storage for the floating-point values displayed in the field. Must have space for at least num values.
num: (in) Is the number of floating-point values to display.
dislen: (in) Is the width of the field in characters.
maxlen: (in) Is the maximum number of characters to use for the textual representation of the floating-point values. In version 4.1.6 and later of IVE 4 and the November 2003 or later versions of IVE 3.3, the value of maxlen has no effect.
min: (in) If the user modifies the floating-point values and min is not equal to max, the changes will be reversed if one or more of the newly entered values is less than min. When min is equal to max, no such check is done. The storage location referenced by min must remain valid as long as the field exists.
max: (in) If the user modifies the floating-point values and min is not equal to max, the changes will be reversed if one or more of the newly entered values is greater than max. When min is equal to max, no such check is done. The storage location referenced by max must remain valid as long as the field exists.
decimal: (in) Holds the number of decimal places to display for each value. If the value referenced by decimal is less than zero, zero decimal places are shown. The storage location referenced by decimal must remain valid as long as the field exists.
callback: (in) When the user finishes editing the contents of the field (either explicitly by pressing Return when the field has input focus or implicitly by causing the field to lose input focus), the WM library will call callback if one or more of the values has changed since the later of the last edit or the last program-initiated update (via one of the WMUpdate routines). The WM library will pass callback a single argument, the value of param (i.e. a pointer to an integer in C and a reference to an integer in Fortran), and expects callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddFloatField is called from C, callback may be zero to signal that no callback should be performed by the WM library when the user edits the field.
param: (in) Is passed as the argument to callback.
update: (in) If update is nonzero and the user finishes an edit that modifies the contents of the field, the WM library will call WMUpdateGroup with the value of group as the argument. If update is zero, the WM library will not call WMUpdateGroup internally when a change occurs.
group: (in) Is a bit mask for the group or groups to which the field will belong.

Return Value

Returns an identification value for the created field.

WMAddFuncButton

Overview

Creates a push button that performs an arbitrary action when pressed.

C Prototype

#include "WMInclude.h"
Widget WMAddFuncButton(char* label, int (*callback)(), int* param, int update, int group);

Fortran Prototype

integer function WMAddFuncButton(label, callback, param, update, group)
integer callback, param, update, group
character*(*) label
external callback

Parameters

label: (in/out) Is the label that will appear on the button. If you call WMAddFuncButton from Fortran and you want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, label must include a null character (i.e. char(0)) to mark the end of the label. label must remain valid for the lifetime of the button. Calls to WMUpdateField or WMUpdateGroup which affect the button will update the label on the button with the current contents of label. If you use WMAddSaveButton in your application, it is dangerous to use a constant string for label: if the user loads previous state, the WM library will write to label if the saved state has a different label than the current one.
callback: (in) When the user presses the button, the WM library will call callback. The WM library will pass callback a single argument, the value of param (i.e. a pointer to an integer in C and a reference to an integer in Fortran), and expects callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddFuncButton is called from C, callback may be zero to signal that no callback should be performed by the WM library when the user presses the button.
param: (in) Is passed as the argument to callback.
update: (in) If update is nonzero and the user presses the button, the WM library will call WMUpdateGroup with the value of group as the argument. If update is zero, the WM library will not call WMUpdateGroup internally when the button is pressed.
group: (in) Is a bit mask for the group or groups to which the button will belong.

Return Value

Returns an identification value for the button created.

WMAddFuncList

Overview

Creates a vertical list of function buttons in a scrolled window. Each function button has an associated button that can display help when pressed.

C Prototype

#include "WMInclude.h"
Widget WMAddFuncList(const char* const* funcname, const char* const* helpindex, int nfunc, int width, int height, int* ifunc, int (*callback)(), int* param, int update);

Fortran Prototype

integer function WMAddFuncList(funcname, helpindex, nfunc, width, height, ifunc, callback, param, update)
integer nfunc, width, height, ifunc, callback, param, update
character*(*) funcname, helpindex
external callback

Parameters

funcname: (in) In C, funcname is an array of nfunc null-terminated strings where the ith element is the label for the ith function button. In Fortran, funcname is a character array containing the labels for each function button separated by tildes (for instance, with four buttons you could use 'one~two~three~four~' to have the first button labeled "one", the second button labeled "two", and so on). If you call WMAddFuncButton from Fortran and you want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, funcname must include a null character (i.e. char(0)) to mark the end of the button names.
helpindex: (in) In C, helpindex may be zero, indicating that no help is available for the function buttons. If helpindex is nonzero, it is assumed to be an array of nfunc null-terminated strings where the ith element is the help keyword for the ith button. In Fortran, helpindex is a character array containing the help keywords for each function button separated by tildes (for instance, with four buttons you could use 'MyApp One~MyApp Two~MyApp Three~MyApp Four~' to specify the keywords for the four buttons). For more information about help keywords, look at the description of WMAddInfoButton. If you call WMAddFuncButton from Fortran and you want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, helpindex must include a null character (i.e. char(0)) to mark the end of the help topic names.
nfunc: (in) Is the number of function buttons in the list.
width: (in) Is the width, in pixels, for the visible area of the scrolled window. If width is less than or equal to zero, the scrolled window extends to the right edge of the parent dialog.
height: (in) Is the height, in pixels, for the visible area of the scrolled window. If height is less than or equal to zero, the scrolled window will be one hundred pixels high.
ifunc: (out) References the integer where the zero-based index (i.e. from zero to nfunc minus one) of the last function button pressed will be stored.
callback: (in) When the user presses one of the function buttons in the list, the WM library will set ifunc to the zero-based index of the button pressed and then call callback. The WM library will pass callback a single argument, the value of param (i.e. a pointer to an integer in C and a reference to an integer in Fortran), and expects callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddFuncButton is called from C, callback may be zero to signal that no callback should be performed by the WM library when the user presses a button in the list.
param: (in) Is passed as the argument to callback.
update: (in) Is present for backward compatibility and has no effect on the behavior of the list of function buttons.

Return Value

Returns the identification value for the list of function buttons.

WMAddGetFile

Overview

Creates a control for selecting a file. The control has a button which will display a file selection dialog when pressed and an adjacent text field which displays the current file name and allows direct entry of the name.

C Prototype

Widget WMAddGetFile(const char* label, char* dir, char* pattern, int maxlen, int dislen, char* filename, int (*callback)(), int* param, int update, int group);

Fortran Prototype

integer function WMAddGetFile(label, dir, pattern, maxlen, dislen, filename, callback, param, update, group)
integer maxlen, dislen, callback, param, update, group
character*(*) label, dir, pattern, filename
external callback

Parameters

label: (in) Is the label displayed on the function button. If you call WMAddGetFile from Fortran and you want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, label must include a null character (i.e. char(0)) to mark the end of the label.
dir: (in) For compatibility with previous versions, you should pass a null-terminated string or zero for dir if you call WMAddGetFile from C or a character array which includes a terminating null character if you call WMAddGetFile from Fortran. In all versions, dir has no effect on the behavior of the control. It was intended to be the initial directory for the file browser, but the starting directory and file name filter for the file browser will always be those associated with the keys set by the most recent call to WMSetGetFileSrc when user presses the file selection button.
pattern: (in) For compatibility with previous versions, you should pass a null-terminated string or zero for pattern if you call WMAddGetFile from C or a character array which includes a terminating null character if you call WMAddGetFile from Fortran. In all versions, pattern has no effect on the behavior of the control. It was intended to be the initial file name filter for the file browser, but the starting directory and file name filter for the file browser will always be those associated with the keys set by the most recent call to WMSetGetFileSrc when user presses the file selection button.
maxlen: (in) Is the maximum number of characters filename can hold. If called from C, maxlen should include the space for the terminating null. If called from Fortran, WMAddGetFile, will use the smaller of maxlen and the maximum length of filename as the maximum number of characters to store in text.
dislen: (in) Is the number of characters from filename to display at one time.
filename: (in/out) Is the storage for the file name. If WMAddGetFile is called from C or C++, text should be a null-terminated string capable of holding at least maxlen characters (including the terminating null character). If WMAddCharField is called from Fortran, text should be a character array (if you also want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, filename must include a null character (i.e. char(0)) to mark the end of the name).
callback: (in) When the user completes editing the file name displayed in the file field (either explicitly by pressing Return when the field has input focus or implicitly by causing the field to lose input focus) and the contents of the field have changed since the later of the last edit or the last program-initiated update (via one of the WMUpdate routines) or the user selects a file via the file browser, the WM library will call callback. The WM library passes callback a single argument, the value of param (i.e. a pointer to an integer in C and a reference to an integer in Fortran), and expects callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddGetFile is called from C, callback may be zero to signal that no callback should be performed by the WM library when the user edits file name field is edited or selects a file via the file browser.
param: (in) Is passed as the argument to callback.
update: (in) If update is nonzero and the user finishes an edit that modifies the contents of the file name field or selects a file via the file browser, the WM library will call WMUpdateGroup with the value of group as the argument. If update is zero, the WM library will not call WMUpdateGroup internally when a change occurs.
group: (in) Is a bit mask for the group or groups to which the control will belong.

Return Value

Returns an identification value for the control.

WMAddGLwMDrawWidget

Overview

Creates a canvas (a GLwMDrawingAreaWidget) where you can do custom drawing via direct calls to the OpenGL libraries. The canvas is double-buffered and operates in RGB mode.

C Prototype

#include "WMInclude.h"
Widget WMAddGLwMDrawWidget(int width, int height, int (*expose_callback), int* ex_param, int (*input_callback)(), int* input_param, GLXContext* context);

Fortran Prototype

No Fortran interface is available.

Parameters

width: (in) Is the width, in pixels, of the drawing area.
height: (in) Is the height, in pixels, of the drawing area.
expose_callback: (in) If not zero, the WM library calls this function when the drawing area is exposed (i.e. needs to be redrawn). The WM library passes the function three arguments: the Widget for the drawing area, an XtPointer which is equivalent to the pointer value ex_param, and an XtPointer to a GLwDrawingAreaCallbackStruct. Though declared as returning an integer, expose_callback is invoked internally as if it did not return a value.
ex_param: (in) Is passed as the second argument to expose_callback.
input_callback: (in) If not zero, the WM library calls this function when the drawing area receives an input event. The WM library passes the function three arguments: the Widget for the drawing area, an XtPointer which is equivalent to the pointer value input_param, and an XtPointer to a GLwDrawingAreaCallbackStruct. Though declared as returning an integer, input_callback is invoked internally as if it did not return a value.
input_param: (in) Is passed as the second argument to input_callback.
context: (out) After realizing the drawing area, the WM library sets *context to the GLXContext created for the canvas. You will need the context for GLwDrawingAreaMakeCurrent(). The WM library will destroy the context when the canvas is destroyed.

Return Value

Returns an identification value for the drawing area created.

WMAddHorSlider

Overview

Creates a control for selecting an integer value from a range of possibilities. The control consists of narrow rectangular region displayed horizontally with a marker for the current value. The user can move the marker back and forth to change the value. If you want the control to display the current value as text as well, call WMSliderShowValue before making the call to WMAddHorSlider.

C Prototype

#include "WMInclude.h"
Widget WMAddHorSlider(const char* label, int width, int min, int max, int* ivar, int (*scallback)(), int* param, int (*dcallback), int* dparam, int update, int group);

Fortran Prototype

integer function WMAddHorSlider(label, width, min, max, ivar, scallback, param, dcallback, dparam, update, group)
integer width, min, max, ivar, scallback, param, dcallback, dparam, update, group
character*(*) label
external scallback, dcallback

Parameters

label: (in) Is the label drawn beneath the control. If WMAddHorSlider is called from C, label may be zero and no label will be displayed. If you call WMAddHorSlider from Fortran and want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, label must include a null character (i.e. char(0)) to mark the end of the label.
width: (in) Is the length, in pixels, of the narrow rectangular part of the control. If width is zero, the rectangle is attached to the right edge of the parent dialog.
min: (in) Is the minimum allowed value. min must be less than max.
max: (in) Is the maximum allowed value. max must be greater than min.
ivar: (in/out) Holds the value corresponding to the current slider position.
scallback: (in) The WM library calls this routine when the user changes the value by interacting with the control. The WM library passes scallback a single argument, the value of param (i.e. a pointer to an integer in C and a reference to an integer in Fortran), and expects scallback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddHorSlider is called from C, callback may be zero to signal that no callback should be performed by the WM library when the value changes.
param: (in) Is passed as the argument to scallback.
dcallback: (in) As the user drags the marker in the control, the WM library will call this routine. The WM library will pass dcallback a single argument, the value of dparam (i.e. a pointer to an integer in C and a reference to an integer in Fortran), and expects dcallback to return an integer value (the particular value returned, however, has not effect on the behavior of the WM library). When WMAddHorSlider is called from C, dcallback may be zero to signal that no callback should be performed as the user drags the marker.
dparam: (in) Is passed as the argument to scallback.
update: (in) If update is nonzero and the user changes the value or is in the process of dragging the marker and dcallback is nonzero, the WM library will call WMUpdateGroup with the value of group as the argument. If update is zero, the WM library will not call WMUpdateGroup internally when a change occurs.
group: (in) Is a bit mask for the group or groups to which the control will belong.

Return Value

Returns an identification value for the created control.

WMSliderShowValue

Overview

Affects whether or not calls to WMAddHorSlider made after the call to WMSliderShowValue will create controls where the current value is also displayed as a text label above the control. If WMSliderShowValue has not been called, controls created by WMAddHorSlider do not display the current value as a label.

C Prototype

#include "WMInclude.h"
int WMSliderShowValue(int flag);

Fortran Prototype

integer function WMSliderShowValue(flag)
integer flag

Parameters

flag: (in) If flag is not equal to zero, subsequent calls to WMAddHorSlider will create controls which display the current value as a label above the control. If flag is zero, subsequent calls to WMAddHorSlider create controls which do not display the current value as a label.

Return Value

Returns zero.

WMAddInfoButton

Overview

Creates a button that, when pressed, displays a particular piece of documentation in the help viewer.

C Prototype

#include "WMInclude.h"
Widget WMAddInfoButton(const char* label, const char* keyword);

Fortran Prototype

integer function WMAddInfoButton(label, keyword)
character*(*) label, keyword

Parameters

label: (in) Is the label to use for the button. If you call WMAddInfoButton from Fortran and want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, label must include a null character (i.e. char(0)) to mark the end of the label.
keyword: (in) Specifies the piece of documentation to display. keyword is expected to contain the base name of the help file optionally followed by a single space and the name of the specific topic. If the base name of the help file does not start with "/", then the library will prepend the path to the installed Priism help files. The library will also append either ".html" or ".hlp" to the base name of the help file depending on the current preference for the help format. If a topic name is provided, it must not contain a space. For ".html" files, the help viewer attempts to jump to the anchor in the file that matches the topic name. For ".hlp" files, the help viewer will display the section whose title matches the topic name. If a topic name is not provided, pressing the button will display the file without jumping to a specific anchor when using a ".html" file and will display the DESCRIPTION section when using a ".hlp" file. When WMAddInfoButton is called from C, keyword may be zero, and in that case, pressing the button will cause a message to be displayed to the user explaining that no help is available. The space pointed to by keyword must remain valid for the lifetime of the button. If you call WMAddInfoButton from Fortran and want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, keyword must include a null character (i.e. char(0)) to mark the end of the keyword.

Return Value

Returns an identification value for the created button.

WMAddIntField

Overview

Creates a field which will display one or more integer values that the user can modify.

C Prototype

#include "WMInclude.h"
Widget WMAddIntField(int* iptr, int num, int dislen, int maxlen, int* min, int* max, int* factor, int (*callback)(), int* param, int update, int group);

Fortran Prototype

integer function WMAddIntField(iptr, num, dislen, maxlen, min, max, factor, callback, param, update, group)
integer num, iptr(num), dislen, maxlen, min, max, factor, callback, param, update, group
external callback

Parameters

iptr: (in/out) Is the storage for the integer values displayed in the field. Must have space for at least num values.
num: (in) Is the number of integer values to display.
dislen: (in) Is the width of the field in characters.
maxlen: (in) Is the maximum number of characters to use for the textual representation of the integer values. In version 4.1.6 and later of the IVE 4 and the November 2003 or later versions of IVE 3.3, the value of maxlen has no effect.
min: (in) If the user modifies the integer values and min is not equal to max, the changes will be reversed if one or more of the newly entered values is less than min. When min is equal to max, no such check is done. The storage location referenced by min must remain as long as the field exists.
max: (in) If the user modifies the integer values and min is not equal to max, the changes will be reversed if one or more of the newly entered values is greater than max. When min is equal to max, no such check is done. The storage location referenced by max must remain as long as the field exists.
factor: (in) If the user modifies the integer values, the changes will be reversed if one or more of the newly entered values is not evenly divisible by factor. The storage location referenced by factor must remain as long as the field exists.
callback: (in) When the user finishes editing the contents of the field (either explicitly by pressing Return when the field has input focus or implicitly by causing the field to lose input focus), the WM library will call callback if one or more of the values has changed since the later of the last edit or the last program-initiated update (via one of the WMUpdate routines). The WM library will pass callback a single argument, the value of param (i.e. a pointer to an integer in C and a reference to an integer in Fortran), and expects callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddIntField is called from C, callback may zero to signal that no callback should be performed by the WM library when the user edits the field.
param: (in) Is passed as the argument to callback.
update: (in) If update is nonzero and the user finishes an edit that modifies the contents of the field, the WM library will call WMUpdateGroup with the value of group as the argument. If update is zero, the WM library will not call WMUpdateGroup internally when a change occurs.
group: (in) Is a bit mask for the group or groups to which the field will belong.

Return Value

Returns an identification value for the created field.

WMAddOnOffStatus

Overview

Creates an indicator light to signal whether something is on or off.

C Prototype

#include "WMInclude.h"
Widget WMAddOnOffStatus(const char* label, int* ivar, int group);

Fortran Prototype

integer function WMAddOnOffStatus(label, ivar, group)
character*(*) label
integer ivar, group

Parameters

label: (in) Is the label to display next to the indicator. If you call WMAddOnOffStatus from Fortran and want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, label must include a null character (i.e. char(0)) to mark the end of the label.
ivar: (in) Holds the value which sets whether the light is on or off. If the value is not equal to zero, the light is on; if the value is equal to zero, the light is off.
group: (in) Is a bit mask for the group or groups to which the control will belong.

Return Value

Returns an identification value for the created indicator.

WMAddOptionMenu

Overview

Creates a control for selecting one option from a limited set of options. The full list of options is only displayed when the user clicks on the control. The current selection is always shown.

C Prototype

#include "WMInclude.h"
Widget WMAddOptionMenu(const char* const* label, int nlabel, int* ichoice, int (*callback)(), XtPointer param, int update, int group);

Fortran Prototype

integer function WMAddOptionMenu(label, nlabel, ichoice, callback, param, update, group)
character*(*) label
integer nlabel, ichoice, callback, param, update, group

Parameters

label: (in) In C, funcname is an array of nlabel null-terminated strings where the ith element is the name of the ith option. In Fortran, label is a character array containing the option names separated by tildes (for instance, with four options you could use 'vanilla~strawberry~chocolate~rocky road~' to have the first option labeled "vanilla", the second labeled "strawberry", and so on). If you call WMAddOptionMenu from Fortran and want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, label must include a null character (i.e. char(0)) to mark the end of the names.
nlabel: (in) Is the number of options available.
ichoice: (in/out) Holds the zero-based index of the currently selected option.
callback: (in) When the user selects an option from the list, the WM library sets ichoice to the index of the selection chosen and calls callback. The WM library will pass callback a single argument, the value of param (i.e. an XtPointer in C and a reference to an integer in Fortran), and will expect callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddOptionMenu is called from C, callback may be zero, and, in that case, the WM library will not invoke a callback when the user changes the selection.
param: (in) Is passed as the argument to callback.
update: (in) If update is nonzero and the user selects an option from the list, the WM library will call WMUpdateGroup with the value of group as the argument. If update is zero, the WM library will not call WMUpdateGroup internally when the user selects an option from the list.
group: (in) Is a bit mask for the group or groups to which the menu will belong.

Return Value

Returns an identification value for the control.

WMAddNestedPulldown

Overview

Creates a new menu bar with a single menu or adds a menu to an existing menu bar. The menu created can have child menus which appear from one or more of the menu's entries: use WMAddPullRight to add the child menus. Each menu created will have tear-off menu capability.

C Prototype

#include "WMInclude.h"
Widget WMAddNestedPulldown(Widget ref, const char* menu_name, const int itemTypes[], const char* const* label, int nlabel, int* ichoice, int (*callback)(), int* param, int update, int group);

Fortran Prototype

integer function XtParent(w)
integer w
integer function WMAddNestedPulldown(ref, menu_name, itemTypes, label, nlabel, ichoice, callback, param, update, group)
integer ref, nlabel, ichoice, param, update, group, itemTypes(nlabel), callback
character*(*) menu_name, label
external callback

Params

ref

(in) To create the first menu in a menu bar, pass zero for ref. To add the menu to the end of an already existing menu bar, pass XtParent(w) for ref where w is the value returned by the call to WMAddNestedPulldown that created the menu bar you wish to extend.

menu_name

(in) Is the title for the pulldown menu that will be created.

itemTypes

(in) Is an integer array with nlabel elements. The ith element of itemTypes sets the format for the ith entry in the menu. Allowed options for the ith element of itemTypes are:

0: The ith entry in the menu is labeled with the ith part of label and does not lead to another menu. If you pass a non-zero value for callback, that routine will be called when the user selects the entry.
1: The ith entry in the menu is labeled with the ith part of the label and leads to another menu.
2: The ith entry in the menu will be a horizontal separator. The ith part of label is ignored. Support for separators was added in the June 1999 release.

label

(in) In C, label is an array of nlabel null-terminated strings where the ith element is used as the label for the ith entry in the menu (unless the ith entry is a separator; then the ith element of label is ignored). In Fortran, label is a character array containing the menu labels separated by tildes (for instance, you could use 'New~Open~Save~~Quit~' for a menu with five entries where the fourth entry is a separator).

nlabel

(in) Is the number of entries in the menu.

ichoice

(out) Holds the zero-based index of the last option the user selected.

callback

(in) When the user selects an entry in the menu that is not a separator and does not lead to another menu, the WM library sets ichoice to the index of the entry selected and calls callback. The WM library will pass callback a single argument, the value of param (i.e. a pointer to an integer in C and a reference to an integer in Fortran), and will expect callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddNestedPulldown is called from C, callback may be zero, and, in that case, the WM library will not invoke a callback when the user selects an entry from the menu.

param

(in) Is passed as the argument to callback.

update

(in) If update is nonzero and the user selects an option from the menu that is not a separator and does no lead to another menu, the WM library will call WMUpdateGroup with the value of group as the argument. If update is zero, the WM library will not call WMUpdateGroup internally when the user selects an item from the menu.

group

(in) Is a bit mask for the group or groups to which the menu will belong.

Return Value

Returns an identification value for the menu created.

Example

The following C code fragment creates a menu bar with two entries ("File" and "Help"). The "File" menu has five entries where the fourth is a separator. The "Help" menu has two entries, the second of which leads to another menu with three entries.

    char* file_menu_labels[] = {
        "ViewFile", "CopyRegion", "Prefs", "", "Quit" 
    }
    int file_menu_types[] = { 0, 0, 0, 2, 0 };
    char* help_menu_labels[] = { "Overview", "File" };
    int help_menu_types[] = { 0, 1 };
    Widget menu, menubar, childmenu;
    static int filechoice, helpchoice, helpfilechoice;

    menu = WMAddNestedPulldown(
        0, "File", file_menu_types, file_menu_labels, 5,
        &filechoice, handle_file_menu, &filechoice, 0, 0
    );
    menubar = XtParent(menu);
    menu = WMAddNestedPulldown(
        menubar, "Help", help_menu_types, help_menu_labels, 2,
        &helpchoice, handle_help_menu, &helpchoice, 0, 0
    );
    childmenu = WMAddPullRight(
        menu, 1, file_menu_types, file_menu_labels, 3,
        &helpfilechoice, handle_help_file_menu, &helpfilechoice, 0, 0
    );

The following Fortran code fragment is a literal translation of the C code above (the Fortran interfaces to WMAddNestedPulldown and WMAddPullRight are only available in IVE 4 versions after 4.1.8).

       integer WMAddNestedPulldown, WMAddPullRight, XtParent
       character file_menu_labels(40), help_menu_labels(20)
       integer file_menu_types(5), help_menu_types(2)
       integer menu, menubar, childmenu
       integer filechoice, helpchoice, helpfilechoice
       integer handle_file_menu, handle_help_menu
       integer  handle_help_file_menu
       external handle_file_menu, handle_help_menu
       external handle_help_file_menu
       save filechoice, helpchoice, helpfilechoice
       data file_menu_labels / 'ViewFile~CopyRegion~Prefs~~Quit~' /
       data file_menu_types / 0, 0, 0, 2, 0 /
       data help_menu_labels / 'Overview~File~' /
       data help_menu_types / 0, 1 /

       menu = WMAddNestedPulldown(
      &    0, "File", file_menu_types, file_menu_labels, 5,
      &    filechoice, handle_file_menu, filechoice, 0, 0)
       menubar = XtParent(menu)
       menu = WMAddNestedPulldown(
      &    menubar, "Help", help_menu_types, help_menu_labels, 2,
      &    helpchoice, handle_help_menu, helpchoice, 0, 0)
       childmenu = WMAddPullRight(
      &    menu, 1, file_menu_types, file_menu_labels, 3,
      &    helpfilechoice, handle_help_file_menu, helpfilechoice, 0, 0)

WMAddPullRight

Overview

Creates a menu that comes off another menu created by either a call to WMAddNestedPulldown or a call to WMAddPullRight. For an example code fragment that uses both WMAddNestedPulldown and WMAddPullRight, consult the WMAddNestedPulldown documentation.

C Prototype

#include "WMInclude.h"
Widget WMAddPullRight(Widget ref, int element, const int itemTypes[], const char* const* label, int nlabel, int* ichoice, int (*callback)(), XtPointer param, int update, int group);

Fortran Prototype

integer function WMAddPullRight(ref, element, itemTypes, label, nlabel, ichoice, callback, param, update, group)
integer ref, element, nlabel, itemTypes(nlabel), ichoice, callback, param, update, group
character*(*) label
external callback

Parameters

ref

(in) Is the identification value for the menu that leads to the menu to be created. ref must be the result of a call to WMAddNestedPulldown or WMAddPullRight.

element

(in) Is the zero-based index for the menu entry in ref that leads to the menu to be created.

itemTypes

(in) Is an integer array with nlabel elements. The ith element of itemTypes sets the format for the ith entry in the menu. Allowed options for the ith element of itemTypes are:

0: The ith entry in the menu is labeled with the ith part of label and does not lead to another menu. If you pass a non-zero value for callback, that routine will be called when the user selects the entry.
1: The ith entry in the menu is labeled with the ith part of the label and leads to another menu.
2: The ith entry in the menu will be a horizontal separator. The ith part of label is ignored. Support for separators was added in the June 1999 release.

label

nlabel

(in) Is the number of entries in the menu.

ichoice

(out) Holds the zero-based index of the last option the user selected.

callback

(in) When the user selects an entry in the menu that is not a separator and does not lead to another menu, the WM library sets ichoice to the index of the entry selected and calls callback. The WM library will pass callback a single argument, the value of param (i.e. an XtPointer in C and a reference to an integer in Fortran), and will expect callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddNestedPulldown is called from C, callback may be zero, and, in that case, the WM library will not invoke a callback when the user selects an entry from the menu.

param

(in) Is passed as the argument to callback.

update

group

(in) Is a bit mask for the group or groups to which the menu will belong.

Return Value

Returns an identification value for the menu created.

WMAddPulldown

Overview

Creates a control for selecting one option from a limited set of options. The full list of options is only displayed when the user clicks on the control. The label shown on the control depends on the last call to WMSetPulldownChoice before the control was created. If WMSetPulldownShowChoice has not been called or was last called with a nonzero argument, the menu will always display the current choice. That behavior is identical to what WMAddOptionMenu does, but the control created by WMAddPulldown takes up less space and, as drawn on the screen, lacks the rectangular knob which is intended as a hint to the user that more choices are available. If WMSetPulldownShowChoice has been called with an argument of zero, the menu will always display the menu title (the last element of label), i.e. act like a menu bar which contains only one menu. For more flexible ways of creating menu bars, use WMAddPulldownMenu or WMAddNestedPulldown.

C Prototype

#include "WMInclude.h"
Widget WMAddPulldown(const char* const* label, int nlabel, int* ichoice, int (*callback)(), int* params, int update, int group);

Fortran Prototype

integer function WMAddPulldown(label, nlabel, ichoice, callback, params, update, group)
integer nlabel, ichoice, callback, params, update, group
character*(*) label
external callback

Parameters

label: (in) In C, label is an array of null-terminated strings. The first nlabel elements of the array are the labels for the choices in the menu. If WMSetPulldownShowChoice has been called and when called last was passed zero as the argument, label is expected to have an additional element which will be used as the title for the menu. In Fortran, label is a character array containing the menu labels separated by tildes. If WMSetPulldownShowChoice has been called and when called last was passed zero as the argument, label is also expected to contain the title for the menu after all the labels (for instance, you could use 'Red~Green~Blue~Color~' for a menu with three entries that displays a menu title rather than the last selection). If you call WMAddPulldown from Fortran and want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, label must include a null character (i.e. char(0)) to mark the end of the names.
nlabel: (in) Is the number of entries in the menu.
ichoice: (in/out) Holds the zero-based index of the last option the user selected. If WMSetPulldownShowChoice has not been called or was last called with a nonzero argument, ichoice is expected to hold the initial value for the current selection when WMAddPulldown is called.
callback: (in) When the user selects an entry in the menu, the WM library sets ichoice to the index of the entry selected and calls callback. The WM library will pass callback a single argument, the value of params (i.e. a pointer to an integer in C and a reference to an integer in Fortran), and will expect callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddPulldown is called from C, callback may be zero, and, in that case, the WM library will not invoke a callback when the user selects an entry from the menu.
params: (in) Is passed as the argument to callback.
update: (in) If update is nonzero and the user selects an option from the menu, the WM library will call WMUpdateGroup with the value of group as the argument. If update is zero, the WM library will not call WMUpdateGroup internally when the user selects an item from the menu.
group: (in) Is a bit mask for the group or groups to which the field will belong.

Return Value

Returns an identification value for the menu created.

WMSetPulldownShowChoice

Overview

The behavior of a control created by WMAddPulldown depends on how WMSetPulldownShowChoice has been called prior to the call to WMAddPulldown. If WMSetPulldownShowChoice has not been called or was last called with a nonzero argument, the created menu will display the current selection as the menu's title. If WMSetPulldownShowChoice has been called and was last called with zero as the argument, the created menu will not display the current selection as the menu's title.

C Prototype

#include "WMInclude.h"
int WMSetPulldownShowChoice(int flag);

Fortran Prototype

integer function WMSetPulldownShowChoice(flag)
integer flag

Parameters

flag: (in) If flag is nonzero, subsequent calls to WMAddPulldown will create controls that display the current selection as the menu's title. If flag is zero, subsequent calls to WMAddPulldown will create controls that do not display the current selection as the menu's title.

Return Value

Returns IW_SUCCESS (i.e. one).

WMGetPulldownShowChoice

Overview

Returns the current setting for whether or not pulldown menus created by WMAddPulldown display the current selection as the title or instead have a fixed title.

C Prototype

#include "WMInclude.h"
int WMGetPulldownShowChoice(void);

Fortran Prototype

integer function WMGetPulldownShowChoice()

Return Value

Returns zero if a call to WMAddPulldown would create a pulldown which displays a fixed title. Returns a non-zero value if a call to WMAddPulldown would create a pulldown which displays the last selection as the title.

WMAddPulldownMenu

Overview

Creates a new menu bar with a single menu or adds a menu to an existing menu bar. It is similar to WMAddNestedPulldown, but does not allow the created menu to have child menus and, unlike WMAddNestedPulldown, the menu does not have tear-off capability.

C Prototype

#include "WMInclude.h"
Widget WMAddPulldownMenu(Widget ref, const char* menu_name, const char* const* label, int nlabel, int* ichoice, int (*callback)(), XtPointer param, int update, int group);

Fortran Prototype

integer function XtParent(w)
integer w
integer function WMAddPulldownMenu(ref, menu_name, label, nlabel, ichoice, callback, param, update, group)
character*(*) menu_name, nlabel
integer ref, nlabel, ichoice, callback, param, update, group
external callback

Parameters

ref: (in) To create the first menu in a menu bar, pass zero for ref. To add the menu to the end of an already existing menu bar, pass XtParent(w) for ref where w is the value returned by the call to WMAddPulldownMenu that created the menu bar you wish to extend.
menu_name: (in) Is the title for the pulldown menu that will be created.
label: (in) In C, label is an array of nlabel null-terminated strings where the ith element is used as the label for the ith entry in the menu (unless the ith entry is a separator; then the ith element of label is ignored). In Fortran, label is a character array containing the menu labels separated by tildes (for instance, you could use 'New~Open~Save~Quit~' for a menu with four entries). If an entry's label is equal to "separator", a horizontal separator will be drawn for that menu entry.
nlabel: (in) Is the number of entries in the menu.
ichoice: (out) Holds the zero-based index of the last option the user selected.
callback: (in) When the user selects an entry in the menu that is not a separator, the WM library sets ichoice to the index of the entry selected and calls callback. The WM library will pass callback a single argument, the value of param (i.e. an XtPointer in C and a reference to an integer in Fortran), and will expect callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddPulldownMenu is called from C, callback may be zero, and, in that case, the WM library will not invoke a callback when the user selects an entry from the menu.
param: (in) Is passed as the argument to callback.
update: (in) If update is nonzero and the user selects an option from the menu that is not a separator, the WM library will call WMUpdateGroup with the value of group as the argument. If update is zero, the WM library will not call WMUpdateGroup internally when the user selects an item from the menu.
group: (in) Is a bit mask for the group or groups to which the field will belong.

Return Value

Returns an identification value for the menu created.

Example

The following C code fragment creates a menu bar with two entries ("File" and "Edit"). The "File" menu has five entries where the fourth is a separator. The "Edit" menu has four entries.

    char* file_menu_labels[] = {
        "New", "Open", "Save", "separator", "Quit"
    };
    char* edit_menu_labels[] = {
        "Cut", "Copy", "Paste", "Select All"
    };
    Widget menu, menubar;
    static int filechoice, editchoice;

     menu = WMAddPulldownMenu(
         0, "File", file_menu_labels, 5, &filechoice,
         handle_file_menu, &filechoice, 0, 0
     );
     menubar = XtParent(menu);
     menu = WMAddPulldownMenu(
         menubar, "Edit", edit_menu_labels, 4, &editchoice,
         handle_edit_menu, &editchoice, 0, 0
     );

The following Fortran code fragment is a literal translation of the C code above (the Fortran interface to WMAddPulldownMenu is only available in IVE 4 versions after 4.1.8).

       integer WMAddPulldownMenu, XtParent
       character file_menu_labels(40), edit_menu_labels(40)
       integer menu, menubar
       integer filechoice, editchoice
       integer handle_file_menu, handle_edit_menu
       external handle_file_menu, handle_edit_menu
       save filechoice, editchoice
       data file_menu_labels / 'New~Open~Save~separator~Quit~' /
       data help_menu_labels / 'Cut~Copy~Paste~Select All~' /

       menu = WMAddPulldownMenu(
      &    0, "File", file_menu_labels, 5, filechoice,
      &    handle_file_menu, filechoice, 0, 0)
       menubar = XtParent(menu)
       menu = WMAddPulldownMenu(
      &    menubar, "Edit", edit_menu_labels, 2, editchoice,
      &    handle_edit_menu, editchoice, 0, 0)

WMAddSaveButton

Overview

Adds a pair of buttons. The first button, labeled "Save", will save the current state of all WM user interface controls when pressed. The second button, labeled "Restore", will restore settings previously saved.

If you use WMAddSaveButton, be aware of the following:

Only the first call to WMAddSaveButton made by an application creates buttons; all subsequent calls do nothing and return zero.
The information saved and retrieved is sensitive to the order in which the WM controls were created and the type of controls. If you rearrange the controls or change the types of controls used, reloading an old settings file will not work as intended.
When settings are restored, they are processed in the order they were created before the settings were saved. If you have dependencies between controls (consistency checks, for instance), verify that they will work if the controls are updated in that order.
When settings are restored, the callbacks registered by the various WMAdd* routines are called and internal calls to WMUpdateGroup are made if values change. You will want to structure your application so that is sufficient to maintain consistency between whatever internal state your application has and the values and settings handled directly by the WM library.
Some state is not saved:
- the current labels for buttons created with WMAddFuncList, WMAddGetFile, WMAddInfoButton, and WMAddToggleButton (labels on buttons created with WMAddFuncButton are saved) and for controls created with WMAddHorSlider, WMAddOnOffStatus, and WMAddStatusBar
- the current labels and enabled/disabled state for entries in menus created with WMAddNestedPulldown, WMAddOptionMenu, WMAddPulldown, WMAddPulldownMenu, and WMAddPullRight
- the current value shown by a control created with WMAddOnOffStatus
- the current contents and maximum number of lines in a control created by WMAddScrolledText
- the current contents of drawing areas created by WMAddDrawingArea and WMAddGLwMDrawWidget

C Prototype

#include "WMInclude.h"
Widget WMAddSaveButton(const char* filename);

Fortran Prototype

integer function WMAddSaveButton(filename)
character*(*) filename

Parameters

filename: (in) Is the name of the file to use when saving and restoring the state of the controls. If the first character in the file name is different then '/', the WM library will construct the file name by prepending the given file name with the user's home directory. The memory referenced by filename must remain valid for as long as the save and restore buttons exist. If you call WMAddSaveButton from Fortran and want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, filename must include a null character (i.e. char(0)) to mark the end of the file name.

Return Value

The first time WMAddSaveButton is called, returns an identification value for the buttons created; otherwise, returns zero.

WMAddScrolledChoices

Overview

Creates a control which displays a list of choices in a window with scroll bars.

C Prototype

#include "WMInclude.h"
Widget WMAddScrolledChoices(char** strings, int* num_items, int num_visible, int (*callback)(), int* params, int group);

Fortran Prototype

integer function WMAddScrolledChoices(strings, num_items, num_visible, callback, params, group)
character*(*) strings
integer num_items, num_visible, callback, params, group
external callback

Parameters

strings: (in/out) In C, strings is an array of *num_items null-terminated strings where the ith element is the name of the ith choice. In Fortran, label is a character array containing the names of the choices separated by tildes (for instance, with three choices you could use 'mean~median~standard deviation~' to have the first choice labeled "mean", the second labeled "median", and so on). If your application updates the scrolled choices control with WMUpdateGroup or WMUpdateField, the WM library will regenerate the contents of the scrolled choices from the current contents of strings and num_items. If your application uses a save/restore button generated with WMAddSaveButton, the WM library will write to strings and num_items during a restore operation and read from them during a save operation.
num_items: (in/out) Refers to the number of items in the list. After the control has been created, the situations where the WM library will access the integer referred to by num_items are mentioned above in the description of the strings parameter.
num_visible: (in) Is the number of items that will be visible at one time.
callback: (in) When the user selects a choice from the list, the WM library calls callback. The WM library will pass callback two arguments. The first is the zero-based index of the selected item. If WMAddScrolledChoices was called from C, the first argument will be passed as an integer; if WMAddScrolledChoices was called from Fortran, the first argument will be passed as a reference to an integer. The second argument is the value of params (i.e. a pointer to an integer in C and a reference to an integer in Fortran). The WM library expects callback to return an integer value (the particular value returned, however, has no effect on the behavior of the WM library). When WMAddScrolledChoices is called from C, callback may be zero, and, in that case, the WM library will not invoke a callback when the user changes the selection.
params: (in) Is passed as the second argument to callback.
group: (in) Is a bit mask for the group or groups to which the control will belong.

Return Value

Returns an identification value for the created control.

WMAddScrolledText

Overview

Creates a control that displays text in a scrolled window. The control does not allow the user to edit the text. Each time the control is updated via WMUpdateGroup or WMUpdateField, the current contents of the first argument passed to WMAddScrolledText are appended to the text and, if necessary, lines at the start of the text are deleted so that the total number of lines is not greater than the value of the integer referred to by the second argument passed to WMAddScrolledText.

C Prototype

#include "WMInclude.h"
Widget WMAddScrolledText(const char* text, const int* nitem, int nvis, int group);

Fortran Prototype

integer function WMAddScrolledText(text, nitem, nvis, group)
character*(*) text
integer nitem, nvis, group

Parameters

text: (in) Refers to a single line of text. If you call WMAddScrolledText from C, text must be a null-terminated string. If you call WMAddScrolledText from Fortran and want to be compatible with IVE 3.3 or versions of IVE 4 earlier than 4.2.0, text must include a null character (i.e. char(0)) to mark the

WMMenu Programming Library

Contents

Platform Specifics

Menu Creation

Widgets

Widget Modification

Widget Positioning

Menu Display

Processing Events

Error and Info Popups

File Selection

Monitor Event Handling

Remote Process Event Handling

Window Manager Control

Display/Dialog/Widget Information

Menu Creation Functions

Overview

C Prototype

Fortran Prototype

Parameters

Return Value

Overview

C Prototype

Fortran Prototype

Parameters

Return Value

Overview

C Prototype

Fortran Prototype

Return Value

Overview

C Prototype

Fortran Prototype

Parameters

Return Value

Overview

C Prototype

Fortran Prototype

Parameters

Return Value

Overview

C Prototype

Fortran Prototype

Parameters

Return Value

Widgets Creation Functions

Overview

C Prototype

Fortran Prototype

Parameters

Return Value

Overview

C Prototype

Fortran Prototype

Parameters

Return Value

Overview

C Prototype

Fortran Prototype

Parameters

Return Value

Overview

C Prototype

Fortran Prototype

Parameters

Return Value

Overview

C Prototype

Fortran Prototype

Parameters

Return Value

Overview

C Prototype

Fortran Prototype

Parameters

Return Value

Overview

C Prototype

Fortran Prototype

Parameters