WMMenu Programming Library
Contents
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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).
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
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_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).
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.
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:
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
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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)
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
- (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 'Red~Green~Blue~' for
a menu with three entries).
- 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
- (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.
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.
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).
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.
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)
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:
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.
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.
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 end of the line.
text must remain valid for as long as the control exists.
- nitem
- (in) Refers to the total number of lines of text
available. The integer referenced by nitem must remain valid
for as long as the control exists.
- nvis
- (in) Is the number of lines of text that will be
displayed at one time.
- 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.
Overview
Creates a horizontal line that extends all the way across the current
dialog. Useful (especially when combined with
WMSetOffset to insert blank space before and after
the line), for visually separating distinct groups of controls. To create
a thicker line, call WMAddSeparator multiple times.
C Prototype
#include "WMInclude.h"
Widget WMAddSeparator(void);
Fortran Prototype
integer function WMAddSeparator()
Return Value
Returns an identification value for the separator.
Overview
Adds an output-only control that represents an integer value by a horizontal
thermometer-like display. The control does not allow the user to modify the
value. WMAddStatusBar is useful for creating a control that will display the
progress of an operation which takes a substantial amount of time.
C Prototype
#include "WMInclude.h"
Widget WMAddStatusBar(const char* label, int width, int maxval, int* ivar, int update, int group);
Fortran Prototype
integer function WMAddStatusBar(label, width, maxval, ivar, update, group)
character*(*) label
integer width, maxval, ivar, update, group
Parameters
- label
- (in) Is the label drawn beneath the control. If
WMAddStatusBar is called from C, label may be zero and no label will be
displayed. If you call WMAddStatusBar 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 thermometer.
If width is zero, the thermometer is attached to the right side
of the dialog.
- maxval
- (in) Is the maximum allowed value for the integer
referenced by ivar. maxval must be greater than
zero.
- ivar
- (in/out) Holds the value representing the current
value for the thermometer. Must be greater than or equal to zero and
less than or equal to maxval.
- update
- (in) If update is nonzero and the
value referenced by ivar changes as the result of the user
pressing a Restore button created by
WMAddSaveButton, 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 the user presses a Restore button.
- group
- (in) Is a bit mask for the group or groups to which
the control will belong.
Return Value
Returns the identification value for the created control.
Overview
Adds an output-only control that displays a single line of text. The
control does not allow the user to change the text.
C Prototype
#include "WMInclude.h"
Widget WMAddText(char* text, int maxlen, int group);
Fortran Prototype
integer function WMAddText(text, maxlen, group)
Parameters
- text
- (in/out) Is the storage for the text displayed in the
field. If WMAddText is called from C or C++, text should
be a null-terminated string. If WMAddCharField is called 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 to
display.
- group
- (in) Is a bit mask for the group or groups to which
the control will belong.
Return Value
Returns the identification value for the created control.
Overview
Adds a control which allows the user to set a variable that has two possible
values, on or off. The control's appearance depends on the system used.
On Linux and OS X the control looks like a button. The button sticks out when
the value is off and is pressed in when the value is on.
C Prototype
#include "WMInclude.h"
Widget WMAddToggleButton(const char* label, int* ivar, int (*callback)(), int* params, int update, int group);
Fortran Prototype
integer function WMAddToggleButton(label, ivar, callback, params, update, group)
character*(*) label
integer ivar, callback, params, update, group
external callback
Parameters
- label
- (in) Is the label to display next to the button.
If you call WMAddToggleButton from Fortran and want to be compatible with
IVE 3.3 or versions of IVE 4 earlier than 4.2.0, label must
contain a null character (i.e. char(0)) to mark the end of the label.
- ivar
- (in/out) Holds the value that affects the state of
the button. If the value referred to by ivar is nonzero,
the button will be on; if the value referred to by ivar
is zero, the button will be off.
- callback
- (in) When the user presses the button, the WM
library will update the value referenced by ivar and 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
expects callback to return an integer value (the particular
value returned, however, has no effect on the behavior of the WM library).
When WMAddToggleButton is called from C, callback may zero to
signal that no callback should be performed by the WM library when the
user presses the button.
- params
- (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 field will belong.
Return Value
Returns an identification value for the created button.
Widget Modification Functions
Overview
Disables a control so that it does not respond to user input until a
subsequent call to WMEnableField or
WMEnableGroup reenables the control.
C Prototype
#include "WMInclude.h"
int WMDisableField(Widget w);
Fortran Prototype
integer function WMDisableField(w)
integer w
Parameters
- w
- (in) Is the identification value for the control to
disable. The WM library function used to create the control returns the
identification value for the control.
Return Value
Returns zero.
Overview
Enables a control to receive user input if the control had previously been
disabled.
C Prototype
#include "WMInclude.h"
int WMEnableField(Widget w);
Fortran Prototype
integer function WMEnableField(w)
integer w
Parameters
- w
- (in) Is the identification value for the control to
enable. The WM library function used to create the control returns the
identification value for the control.
Return Value
Returns zero.
Overview
Disables from receiving user input all controls whose group number has a
bit on that is also on in the mask, group, passed as the argument
to WMDisableGroup.
C Prototype
#include "WMInclude.h"
void WMDisableGroup(int group);
Fortran Prototype
integer function WMDisableGroup(group)
integer group
Parameters
- group
- (in) Is the bit mask for the groups of controls to
disable.
Return Value
The C interface does not return a value; the Fortran interface returns zero.
Overview
Enables previously disable controls whose group number has a bit on that
is also on in the mask, group, passed as the argument to
WMEnableGroup.
C Prototype
#include "WMInclude.h"
void WMEnableGroup(int group);
Fortran Prototype
integer function WMEnableGroup(group)
integer group
Parameters
- group
- (in) Is the bit mask for the groups of controls to
enable.
Return Value
The C interface does not return a value; the Fortran interface returns zero.
Overview
Hides a control from view. The control may continue to take up space
in the dialog even though the control is not visible.
C Prototype
#include "WMInclude.h"
int WMUnpasteWidget(Widget w);
Fortran Prototype
integer function WMUnpasteWidget(w)
integer w
Parameters
- w
- (in) Is the identification value for the control to
hide. The WM library function used to create the control returns the
identification value for the control.
Return Value
Returns negative one if w is zero or is known to be invalid;
otherwise, returns zero.
Overview
Makes a control visible if it was previously hidden from view.
C Prototype
#include "WMInclude.h"
int WMPasteWidget(Widget w);
Fortran Prototype
integer function WMPasteWidget(w)
integer w
Parameters
- w
- (in) Is the identification value for the control to
display. The WM library function used to create the control returns the
identification value for the control.
Return Value
Returns negative one if w is zero or is known to be invalid;
otherwise, returns zero.
Overview
Except for the return value, WMInsensitiveGroup functions identically to
WMDisableGroup.
C Prototype
#include "WMInclude.h"
int WMInsensitiveGroup(int group);
Fortran Prototype
integer function WMInsensitiveGroup(group)
integer group
Parameters
- group
- (in) Is the bit mask for the groups of controls to
disable.
Return Value
Returns zero.
Overview
Except for the return value, WMSensitiveGroup functions identically to
WMEnableGroup.
C Prototype
#include "WMInclude.h"
int WMSensitiveGroup(int group);
Fortran Prototype
integer function WMSensitiveGroup(group)
integer group
Parameters
- group
- (in) Is the bit mask for the groups of controls to
enable.
Return Value
Returns zero.
Overview
For all controls whose group number has a bit on that is also on in the mask
group passed as the argument to WMUpdateGroup, updates the user
interface of the control to match the value or values the control represents.
C Prototype
#include "WMInclude.h"
int WMUpdateGroup(int group);
Fortran Prototype
integer function WMUpdateGroup(group)
integer group
Parameters
- group
- (in) Is the bit mask for the groups of controls to
update.
Return Value
Returns zero.
Overview
Updates the user interface of a control to match the value or values the
control represents.
C Prototype
#include "WMInclude.h"
int WMUpdateField(Widget w);
Fortran Prototype
integer function WMUpdateField(w)
integer w
Parameters
- w
- (in) Is the identification value for the control to
update. The WM library function used to create the control returns the
identification value for the control.
Return Value
Returns negative one if w is zero or is known to be invalid;
otherwise, returns zero.
Overview
Changes the entries in a menu created by
WMAddNestedPulldown,
WMAddOptionMenu,
WMAddPulldown,
WMAddPulldownMenu, or
WMAddPullRight. Can change the label for an
entry and whether or not an entry is sensitive to user input. For menus
created by WMAddPulldown, can change a normal
menu entry to a horizontal separator or vice versa. For menus created by
WMAddNestedPulldown,
WMAddPulldownMenu, or
WMAddPullRight, can change the type of the entry
to any of the three supported types (simple entry, entry that leads to another
menu, or horizontal separator). Versions of the WM library prior to IVE 4.2.0
will ignore requests to change the type of a menu entry.
C Prototype
#include "WMInclude.h"
int WMChangePulldown(Widget w, const char* const* new_labels, const int sens_list[], int nlabel);
Fortran Prototype
integer function WMChangePulldown(w, new_labels, sens_list, nlabel)
character*(*) new_labels
integer w, nlabel, sens_list(nlabel)
Parameters
- w
- (in) Is the identification value for the menu to change.
- new_labels
- (in) In C, new_labels 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 new_labels is ignored). In
Fortran, new_labels 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).
- sens_list
- (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
sens_list are:
- 0
- The ith entry is a normal menu entry (it does not lead to
another menu and is not a separator) which is insensitive to user
input. The label for the entry is the ith part of
new_labels
- 1
- The ith entry is a normal menu entry which is sensitive to
user input. The label for the entry is the ith part of
new_labels.
- 2
- The ith entry is a menu entry that leads to another menu
and is insensitive to user input. The label for the entry is the ith
part of new_labels.
- 3
- The ith entry is a menu entry that leads to another menu
and is sensitive to user input. The label for the entry is the ith
part of new_labels
- 4 or 5
- The ith entry is a horizontal separator. The ith part
of new_labels is ignored.
- nlabel
- (in) Is the number of entries to appear in the
updated menu.
Return Value
Return negative one if w is zero, w is not
a menu, or if new_labels is zero. Otherwise, returns one.
Side Effects
- If the menu was created by WMAddPulldown
when the option to show the current choice was enabled or was created by
WMAddOptionMenu, calling WMChangePulldown
will have the effect of also calling
WMUpdateField on the menu.
- If the menu contains entries leading to other menus which are deleted
by the change or replaced by entries of a different type, any child menus
and their descendants of the deleted entries are deleted and further
references to them by the application will lead to undefined behavior.
Overview
Changes the currently selected item in a control created by
WMAddScrolledChoices; does not cause the
update callback to be invoked.
C Prototype
#include "WMInclude.h"
int WMChangeScrolledChoicesSelection(Widget w, int new_selection);
Fortran Prototype
integer function WMChangeScrolledChoicesSelect(w, new_selection)
integer w, new_selection
Parameters
- w
- (in) Is the identification value for the control to
modify (i.e. the value returned by
WMAddScrolledChoices).
- new_selection
- (in) Is the zero-based index of the item
which will be displayed as the current selection. If
new_selection is less than zero or greater than or equal to
the number of items in the list, no item will be shown as the current
selection.
Return Value
Returns one.
Overview
Changes the label on a previously created control. Works on the
controls created by WMAddGetFile,
WMAddInfoButton,
WMAddOnOffStatus,
and WMAddToggleButton and will change the
menu name for menus created with WMAddPulldown,
WMAddPulldownMenu, or
WMAddNestedPulldown. It will also
work on buttons created by WMAddFuncButton,
but in that case you have an alternative mechanism: modify the label
originally passed to WMAddFuncButton and then
call WMUpdateField or
WMUpdateGroup to redraw the button's label
(if your application uses WMAddSaveButton
these two methods are not strictly equivalent: calling WMChangeText will
not affect the program state that is saved when the save button is pressed;
changing the original label and then updating the button will change the
state saved when the save button is pressed). To change the labels on
controls created with WMAddHorSlider or
WMAddStatusBar, use
WMChangeTitle.
C Prototype
#include "WMInclude.h"
int WMChangeText(Widget w, const char* new_string);
Fortran Prototype
integer function WMChangeText(w, new_string)
integer w
character*(*) new_string
Parameters
- w
- (in) Is the identification value for the control to
modify. The WM library function used to create the control returns the
identification value for the control.
- new_string
- (in) Is the new label for the control. If
you call WMChangeText 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.
Return Value
Return negative one if new_string is zero, w is zero,
or if called from Fortran and w does not match a known control
Otherwise, returns one.
Overview
Changes the label on a control created previously with
WMAddHorSlider or
WMAddStatusBar. To change the labels on other
controls, use WMChangeText.
C Prototype
#include "WMInclude.h"
int WMChangeTitle(Widget w, const char* new_string);
Fortran Prototype
integer function WMChangeTitle(w, new_string)
integer w
character*(*) new_string
Parameters
- w
- (in) Is the identification value for the control to
modify. The WM library function used to create the control returns the
identification value for the control.
- new_string
- (in) Is the new label for the control. If
you call WMChangeText 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.
Return Value
Return negative one if new_string is zero, w is zero,
or if called from Fortran and w does not match a known control;
otherwise, return one.
Overview
In the case where you wish to pop up a dialog and immediately draw to
it, you can call WMForceUpdate after popping up the dialog. WMForceUpdate
will return immediately if the dialog containing WMForceUpdate's argument
has not been realized (i.e. it is ready for mapping to the screen); otherwise,
WMForceUpdate will wait until the dialog is mapped to the screen and ready
for drawing. Since WMDisplay and
WMDisplaySubMenu implicitly call WMForceUpdate,
the only situation where you might use WMForceUpdate is if you create your
own dialogs directly with the Xt toolkit.
C Prototype
#include "WMInclude.h"
void WMForceUpdate(Widget w);
Fortran Prototype
subroutine WMForceUpdate(w)
integer w
Parameters
- w
- (in) WMForceUpdate returns immediately if the first
Shell widget ancestor and first TopLevelShell widget ancestor of
w have not been realized; otherwise, it will wait, processing
events, until those shells are visible.
Overview
By default, the WMAdd* routines add controls to the bottom of the
dialog created by the latest of the calls to
WMInit or WMInitSubMenu.
Use WMInsertWidget to change where WMAdd* routines insert controls. That
change lasts until you call WMEndInsert directly
or until you call WMInsertWidget, WMInitSubMenu,
or WMDeleteWidget which will implicitly call
WMEndInsert with an argument of one.
C Prototype
#include "WMInclude.h"
int WMInsertWidget(Widget w, int method);
Fortran Prototype
integer function WMInsertWidget(w, method)
integer w, method
Parameters
- w
- (in) Is the identification value for the existing
control that will serve as the reference point for the inserted controls.
method controls the relationship between the inserted controls
and the reference point. The WM library function used to create the
control returns the identification value for the control.
- method
- (in) Specifies the relationship between the
inserted controls and the existing control w. Allowed
values for method are:
- 0
- The insertion point for new controls starts out immediately
to the right of w; it will then shift to the right and
then downwards as controls are inserted or
WMNewRow is called.
- 1
- The insertion point for new controls starts out at the left
edge of the line below w; it will then shift to the right
and then downwards as controls are inserted or
WMNewRow is called. If w is not at
the end of its line, the remaining controls on the line will
appear immediately to the right of the last control added
in the sequence of insertions initiated by this call to WMInsertWidget.
- 2
- The insertion point for new controls starts out at the left
edge of the line below w; it will then shift to the right
and then downwards as controls are inserted or
WMNewRow is called. If w is not at
the end of its line, the remaining controls on the line will
appear on the line immediately below the last control added
in the sequence of insertions initiated by this call to WMInsertWidget.
Return Value
Returns negative one in case of failure (an invalid value for w
or insufficient memory to proceed). Returns one if successful.
Overview
Terminates the additions to a dialog started by
WMInsertWidget and sets the insertion point
for new controls to its default location, the end of the dialog created by
the latest of the calls to WMInit or
WMInitSubMenu.
C Prototype
#include "WMInclude.h"
int WMEndInsert(int resize_flag);
Fortran Prototype
integer function WMEndInsert(resize_flag)
integer resize_flag
Parameters
- resize_flag
- (in) If resize_flag is not zero,
then WMEndInsert will resize the dialog to fit the controls the dialog now
contains; otherwise, WMEndInsert will not resize the dialog.
Return Value
Returns one.
Overview
Removes a control previously added by a call to one of the WMAdd* routines.
To fill the empty space formerly occupied by the control, moves the remaining
controls but does not disturb how they are organized into lines. If an
insertion initiated with WMInsertWidget is still
active, the call to WMDeleteWidget implicitly terminates the insertion as if
you had explicitly called WMEndInsert with an
argument of one.
C Prototype
#include "WMInclude.h"
int WMDeleteWidget(Widget w, int resize_flag);
Fortran Prototype
integer function WMDeleteWidget(w, resize_flag)
integer w, resize_flag
Parameters
- w
- (in) Is the identification value for the control
to remove. The WM library function used to create the control returns
the identification value for the control.
- resize_flag
- (in) If resize_flag is not zero,
WMDeleteWidget will resize the dialog that contained the control to fit
the controls it still has. Otherwise, WMDeleteWidget will not resize
the dialog.
Return Value
Returns negative one if w is zero or is known to be invalid;
otherwise, returns zero.
Widget Positioning Functions
Overview
Attaches the last control created via a WMAdd* routine to the right
side of the dialog. When the dialog is first shown that control will be
the wider of its natural width or the width needed to extend the control
to the right side of the dialog. If the users changes the width of the
dialog, the control will grow or shrink to fit.
After calling WMAttachRightSide, you'll have to call
WMNewRow before adding subsequent controls to the same
dialog.
C Prototype
#include "WMInclude.h"
void WMAttachRightSide();
Fortran Prototype
subroutine WMAttachRightSide()
Overview
After calling WMNewRow, the next call to a WMAdd* routine (unless
WMInsertWidget is called first and is not
matched with a subsequent WMEndInsert), will place
the new control at the left side of the dialog. The offsets between the new
control and the left side of the dialog and the first control in the previous
row of controls can be set by a call to WMSetOffset
before adding the control.
WMAddFuncList (if the specified width
is less than or equal to zero),
WMAddScrolledChoices,
WMAddScrolledText, and
WMAddSeparator put the controls they
create on their own line in the dialog and are not affected by the presence
or absence of calls to WMNewRow.
C Prototype
#include "WMInclude.h"
Widget WMNewRow(void);
Fortran Prototype
integer function WMNewRow()
Return Value
Returns the identification value for the first widget in the row just
completed.
Overview
Sets the spacing for controls created by subsequent calls to WMAdd*
routines. If WMSetOffset has not been called, WMAdd* calls will function
as if WMSetOffset had been called with all four arguments set to zero.
C Prototype
#include "WMInclude.h"
int WMSetOffset(int left, int right, int top, int bottom);
Fortran Prototype
integer function WMSetOffset(left, right, top, bottom)
integer left, right, top, bottom
Parameters
- left
- (in) After the call to WMSetOffset, the left edge
of a newly added control will be left pixels from either the
right edge of the neighbor to the left or, if the new control is first in
the row, the inside left edge of the dialog. If left is less
than zero, the call to WMSetOffset has no effect.
- right
- (in) After the call to WMSetOffset, a newly added
control whose right side is anchored (by calling
WMAttachRightSide) will have its right
side placed at right pixels to the left of the right edge
of the anchor. If right is less than zero, the call to
WMSetOffset has no effect.
- top
- (in) After the call to WMSetOffset, the top edge
of a newly added control will be top pixels from either the
bottom edge of the first control in the previous row or, if the new control
is in the first row, the inside top edge of the dialog. If
top is less than zero, the call to WMSetOffset has no effect.
- bottom
- (in) After the call to WMSetOffset, a newly added
control whose bottom side is anchored (the WM library does not
provide a function to do this; it could be done with XtSetValues) will
will have its bottom side placed at bottom pixels above the
top edge of the anchor. If bottom is less than zero, the call
to WMSetOffset has no effect.
Return Value
Returns zero.
Menu Display Functions
Overview
WMDisplay displays a dialog created by WMInit
and pushes it to the top of the visible windows.
C Prototype
#include "WMInclude.h"
int WMDisplay(void);
Fortran Prototype
integer function WMDisplay()
Return Value
Returns zero.
Overview
WMDisplaySubMenu displays a dialog created by
WMInitSubMenu or WMInit
and pushes the dialog to the top of the visible windows.
C Prototype
#include "WMInclude.h"
int WMDisplaySubMenu(int w);
Fortran Prototype
integer function WMDisplaySubMenu(w)
integer w
Parameters
- w
- (in) Is the index for the dialog to display. The
dialog created by WMInit has an index of zero.
The index for a dialog created with
WMInitSubMenu is returned by
WMInitSubMenu.
Return Value
Returns zero.
Overview
Hides a dialog created by WMInitSubMenu or
WMInit. To make the dialog visible again,
call WMDisplaySubMenu or,
for the dialog created by WMInit,
WMDisplay.
C Prototype
#include "WMInclude.h"
int WMUndisplaySubMenu(int w);
Fortran Prototype
integer function WMUndisplaySubMenu(w)
integer w
Parameters
- w
- (in) Is the index for the dialog to hide. The dialog
created by WMInit has an index of zero. The
index for a dialog created with WMInitSubMenu
is returned by WMInitSubMenu.
Return Value
Returns zero.
Event Processing Functions
Overview
Enters an endless loop which waits for events from the user interface
and processes them. You normally call this function after you have initialized
your application, created the main dialog, and displayed the main dialog
with WMDisplay.
C Prototype
#include "WMInclude.h"
int WMAppMainLoop(void);
Fortran Prototype
integer function WMAppMainLoop()
Overview
WMProcEvent will process all pending user interface events with the option
to wait until at least one event is processed. WMProcEvent allows for
more flexible event processing then WMAppMainLoop.
C Prototype
#include "WMInclude.h"
int WMProcEvent(int wait);
Fortran Prototype
integer function WMProcEvent(wait)
integer wait
Parameters
- wait
- (in) If wait is not zero, WMProcEvent
will process at least one user interface event, and if no events are
currently pending, WMProcEvent could wait for an indefinite period
of time before returning. If wait is zero, WMProcEvent
will process all pending user interface events and then return.
Return Value
Returns the number of events processed directly by the call to WMProcEvent
(nested event processing in callback functions could cause other events
to be processed which are not reflected in the return value).
Error and Info Popup Functions
Overview
Displays a dialog with a message and two buttons labeled "Ok" and "Cancel"
and then does not return until the user selects one of the options or
dismisses the dialog.
C Prototype
#include "WMInclude.h"
int WMConfirm(const char* message);
Fortran Prototype
integer function WMConfirm(message)
character*(*) message
Parameters
- message
- (in) Holds the text of the message to display.
To have the message displayed on multiple lines, embed a newline character
in message where you would like a line break (support for multiple line
messages was added in the October 1999 release). If WMConfirm is called
from Fortran and you want to be compatible with IVE 3.3 or versions of
IVE 4 earlier than 4.2.0, message must include a null character
(i.e. char(0)) to mark the end of the message.
Return Value
Returns one if the user selects ok; otherwise returns zero if the user
chooses to cancel or closes the dialog via the window manager.
Overview
Returns a pointer to the X event structure for the last button press
on a button created by WMAddArrowButton or
WMAddFuncButton. If all you need from the
event structure is the number of the mouse button involved, you can use
WMGetLastButNum instead.
C Prototype
#include "WMInclude.h"
XEvent* WMRetLastButEvent(void);
Fortran Prototype
pointer_equivalent_integer function WMRetLastButEvent()
Return Value
Returns the address of an X event structure.
Overview
Returns the number of the mouse button pressed from the last time the
user pressed a button created by
WMAddArrowButton or
WMAddFuncButton.
C Prototype
#include "WMInclude.h"
int WMGetLastButNum(void);
Fortran Prototype
integer function WMGetLastButNum()
Return Value
Returns the mouse button number, an integer between one and five.
Overview
Display an error message dialog and does not return until the user dismisses
the dialog.
C Prototype
#include "WMInclude.h"
int WMConfirmError(const char* message);
Fortran Prototype
integer function WMConfirmError(message)
character*(*) message
Parameters
- message
- (in) Holds the text of the message to display.
To have the message displayed on multiple lines, embed a newline character
in message where you would like a line break (support for multiple line
messages was added in the October 1999 release). If WMConfirmMessage is
called from Fortran and you want to be compatible with IVE 3.3 or versions
of IVE 4 earlier than 4.2.0, message must include a null
character (i.e. char(0)) to mark the end of the message.
Return Value
Returns zero.
Overview
Displays a message that, if not dismissed first, will disappear
automatically after a given amount of time has elapsed. As currently
implemented, a call to WMPostInfo will have no effect while the message
from a previous call to WMPostInfo is visible.
C Prototype
#include "WMInclude.h"
int WMPostInfo(const char* message, int second);
Fortran Prototype
integer function WMPostInfo(message, second)
character*(*) message
integer second
Parameters
- message
- (in) Holds the text of the message to display.
To have the message displayed on multiple lines, embed a newline character
in message where you would like a line break (support for multiple line
messages was added in the October 1999 release). If WMPostInfo is
called from Fortran and you want to be compatible with IVE 3.3 or versions
of IVE 4 earlier than 4.2.0, message must include a null
character (i.e. char(0)) to mark the end of the message.
- second
- (in) Is the maximum number of seconds that the
message will be visible.
Return Value
Returns zero.
Overview
Displays a message that will remain visible until dismissed by the user
or until WMRemoveInfo is called.
C Prototype
#include "WMInclude.h"
Widget WMShowInfo(const char* message);
Fortran Prototype
integer function WMShowInfo(message)
character*(*) message
Parameters
- message
- (in) Holds the text of the message to display.
To have the message displayed on multiple lines, embed a newline character
in message where you would like a line break (support for multiple line
messages was added in the October 1999 release). If WMShowInfo is
called from Fortran and you want to be compatible with IVE 3.3 or versions
of IVE 4 earlier than 4.2.0, message must include a null
character (i.e. char(0)) to mark the end of the message.
Return Value
Returns an identification value for the message. Use the returned value
as the argument to WMRemoveInfo when you want to
hide the message.
Overview
Hides a message displayed by WMShowInfo and
releases the resources used to display the message.
C Prototype
#include "WMInclude.h"
int WMRemoveInfo(Widget w)
Fortran Prototype
integer function WMRemoveInfo(w)
integer w
Parameters
- w
- (in) Is the identifier value, returned by
WMShowInfo, for the message to hide.
Return Value
Returns one.
Overview
Causes the help viewer to display a particular topic.
C Prototype
#include "WMInclude.h"
void WMDisplayHelp(const char* keyword);
Fortran Prototype
subroutine WMDisplayHelp(keyword)
character*(*) keyword)
Parameters
- keyword
- Specifies the piece of documentation to
display. See the description of the keyword argument
in the WMAddInfoButton documentation for
more information on how keyword is interpreted.
Overview
Makes the computer beep.
C Prototype
#include "WMInclude.h"
WMRingBell(int ivol, float len);
Fortran Prototype
integer function WMRingBell(ivol, len)
integer ivol
real len
Parameters
- ivol
- (in) Sets the volume of the sound. Allowed values
range from -100 (no sound) to 100 (twice the base volume). If
ivol is zero, the volume is the base volume. Values of
ivol less than -100 are treated as -100, and values of
ival greater than 100 are treated as 100.
- len
- (in) Sets the duration of the tone in seconds.
Return Value
Returns zero.
File Selection Functions
Overview
Displays a file selection dialog and waits for the user to select a file
or dismiss the dialog. The initial directory and pattern shown in the file
selection dialog are extracted from a database using the keys passed in the
last call WMSetGetFileSrc, and when the user
selects a file, WMGetFile copies the directory and filter at the time to the
database.
To create a control that launches a file selection dialog, you could use
WMAddGetFile, or call
WMAddFuncButton and then call WMGetFile from
the button's callback routine. While selecting the file, the user can
interact with other user interface elements. In the common case where
WMGetFile is called from the callback routine for a button added with
WMAddFuncButton, the user could press that
button again (or simply an errant double click in the initial interaction)
which would generate another file selection dialog.
C Prototype
#include "WMInclude.h"
int WMGetFile(char* filename, char* dir, char* pattern, char* filter);
Fortran Prototype
integer function WMGetFile(filename, dir, pattern, filter)
character*(*) filename, dir, pattern
Parameters
- filename
- (out) Is storage for the name of the file that
the user selects. If the user does not select a file, the contents of
filename are not altered by WMGetFile.
- dir
- Present for backward compatibility with earlier
versions of Priism. dir is not accessed in any way in IVE 4.
- pattern
- Present for backward compatibility with earlier
versions of Priism. pattern is not accessed in any way in
IVE 4.
- filter
- Present for backward compatibility with earlier
versions of Priism. filter is not accessed in any way in IVE 4.
Return Value
Returns a value greater than zero if the user selected file. Other
return values indicate that the user dismissed the dialog without
selecting a file.
Overview
Sets the database keys that are used to look up the initial directory and
file name filter when file selection dialogs are displayed (either directly
by WMGetFile or indirectly by the user pressing the
button in a control added by WMAddGetFile).
When the user completes a file selection, the directory and file name filter
associated with the keys are updated to match the settings in the file
selection dialog. If WMSetGetFileSrc has not been
called by an application, the key used for the directory is "IVE_DEF_DIR:"
and the key used for the file name filter is "IVE_DEF_FILE_EXT:". The
database is maintained as a text file called .ivestartup in the user's home
directory.
Common values used for the directory key and file name filter key are shown
below. By convention, different directory keys are used for configuration
data, and the same directory key, "IVE_DEF_DIR:", is used for file types that
are the results of processing.
| Data Type |
Directory Key |
File Name Filter Key |
| MRC image |
"IVE_DEF_DIR:" |
"IVE_DEF_FILE_EXT:" |
| TIFF image |
"IVE_DEF_DIR:" |
"TIFF_FILE_EXT:" |
| 2D Plot file |
"IVE_DEF_DIR:" |
"PLOT_FILE_EXT:" |
| Polygons |
"IVE_DEF_DIR:" |
"POLY_FILE_EXT:" |
| Volume builder association list (old format) |
"IVE_DEF_DIR:" |
"BLD_FILE_EXT:" |
| Pick Points point list (old format) |
"IVE_DEF_DIR" |
"PICK_FILE_EXT:" |
| Model for 3D Model |
"IVE_DEF_DIR:" |
"MOD_FILE_EXT:" |
| Graphic colors description |
"COLOR_DIR:" |
"COLOR_FILE_EXT:" |
| BlendColors color description |
"BLEND_DIR:" |
"BLEND_FILE_EXT:" |
| PostScript output |
"IVE_DEF_DIR:" |
"PSFILE_EXT:" |
C Prototype
#include "WMInclude.h"
void WMSetGetFileSrc(const char* dirkey, const char* patkey);
Fortran Prototype
subroutine WMSetGetFileSrc(dirkey, patkey)
character*(*) dirkey, patkey
Parameters
- dirkey
- (in) After the call to WMSetGetFileSrc, directory
names will be looked up in the database using dirkey as the
key. If the database does not have an entry for dirkey, the
user's home directory will be used initially until the user selects
a file and the database is updated.
- patkey
- (in) After the call to WMSetGetFileSrc, file name
filters will be looked up in the database using patkey as the
key. If the database does not have an entry for patkey, "*.dat"
will be used initially until the user selects a file and the database is
updated.
Monitor Event Handling Functions
Overview
Until WMEnableIWLEvent is called, the application ignores events from
image windows. Once image window events are enabled, you can call
WMDisableIWLEvent to ignore those events
until WMEnableIWLEvent is called again.
C Prototype
#include "WMInclude.h"
void WMEnableIWLEvent(void);
Fortran Prototype
subroutine WMEnableIWLEvent()
Overview
Causes the application to ignore events from image windows. To restore
handling of events from image windows, call
WMEnableIWLEvent.
C Prototype
#include "WMInclude.h"
void WMDisableIWLEvent(void);
Fortran Prototype
subroutine WMDisableIWLEvent()
Overview
Registers a routine to be called when the application receives an
event of a particular type from an image window and the application is
processing image window events (see
WMEnableIWLEvent for details). If you no
longer want the WM library to call a routine in response to an image window
event, call WMCancelEventHandler.
C Prototype
#include "WMInclude.h"
int WMAddEventHandler(int istream, long mask, int (*func)(), int argu);
Fortran Prototype
include 'WM.inc'
integer function WMAddEventHandler(istream, mask, func, argu)
integer istream, mask, func, argu
external func
Parameters
- istream
- (in) If istream is an
IM library stream number associated with an
open image window (via either IMOpen or
IWAttachWin), the routine
registered will be called for events whose type matches one of the
types in mask and which come from that image window. If
istream is less than zero, the routine registered will be
called for events whose type matches one of the types in mask
and which come from any image window.
- mask
- (in) Specifies the type or types of events that will
cause the routine to be called. mask may be a one or more of
the constants listed below (for multiple constants, combine them with
bitwise-or operators in C or with addition in Fortran). WMInclude.h
defines the constants for C, and WM.inc defines the constants for Fortran.
- ButtonPressMask
- Specifies the type of events generated when a
mouse button is pressed while the mouse pointer is over the image
portion of an image window. By default, image windows do not pass
along button press events from buttons other than button one of the
mouse. To receive button press events from the other buttons, the
application must also call
WMRegMouseButton.
- ButtonReleaseMask
- Specifies the type of events generated when a
mouse button is released and the corresponding button press occurred
in the image portion of an image window. By default, image windows do
not pass along button release events from buttons other than button
one of the mouse. To receive button release events from the other
buttons, the application must also call
WMRegMouseButton.
- EnterWindowMask
- Specifies the type of events generated when the
mouse pointer enters the image portion of an image window.
- LeaveWindowMask
- Specifies the type of events generated when the
mouse pointer leaves the image portion of an image window.
- PointerMotionMask
- Specifies the type of events generated when
the mouse pointer moves within the image portion of an image window.
- KeyPressMask
- Specifies the type of events generated when a
key on the keyboard is pressed and the image portion of an image
window has input focus.
- KeyReleaseMask
- Specifies the type of events generated when a
key on the keyboard is released and the image portion of an image
window has input focus. Some hardware generates key press events
but does not generate the corresponding release events.
- func
- (in) Is the routine that the WM library will call
when an event arrives that matches one of the types in mask and
which comes from the window specified by istream. When the
WM library calls func, it will pass it two arguments. The
first is the value of argu (an integer if WMAddEventHandler
is called from C or a reference to an integer if WMAddEventHandler is
called from Fortran). The second is the address of the XEvent structure
for the event. The WM library expects func to return an
integer, but the particular value returned has no effect on the behavior
of the library. If func has already been registered for the
same image window and one of the event types in mask and that
registration was not subsequently canceled, the library will not
reregister the function (i.e. call it twice when an event is received) for
the same image window and the same event type.
- argu
- (in) The WM library will pass argu as the
first argument when it calls the registered routine, func.
Return Value
Returns negative one if communication with the image window system could
not be established, if istream is zero or is positive but not
attached to an image window the application has open, or if a memory
allocation error occurred while attempting to register the routine as an
event handler. Otherwise, returns one.
Overview
Cancels the routines registered with
WMAddEventHandler for a set of event
types and either a particular image window or all image windows.
C Prototype
#include "WMInclude.h"
int WMCancelEventHandler(int istream, long mask);
Fortran Prototype
include 'WM.inc'
integer function WMCancelEventHandler(istream, mask)
integer istream, mask
Parameters
- istream
- (in) If istream is an
IM library stream number associated with an
open image window (via either IMOpen or
IWAttachWin), WMCancelEventHandler
will cancel all routines registered for that image window and one of the
event types in mask. If istream is less than zero,
WMCancelEventHandler will cancel all routines, regardless of the source
image window, registered for an event type which matches one of the
event types in mask.
- mask
- (in) Specifies the type or types of events that the
application no longer wishes to handle for the image windows specified
by istream. mask may be a one or more of
the constants listed below (for multiple constants, combine them with
bitwise-or operators in C or with addition in Fortran). WMInclude.h
defines the constants for C, and WM.inc defines the constants for Fortran.
- ButtonPressMask
- ButtonReleaseMask
- EnterWindowMask
- LeaveWindowMask
- PointerMotionMask
- KeyPressMask
- KeyReleaseMask
Return Value
Returns negative one if communication with the image window system could
not be established, if no event handlers have ever been registered,
or if istream is zero or is positive but not attached to an image
window the application has open. Otherwise, returns one.
Overview
Registers a routine to be called when an image window's state changes
and the application is processing image window events (see
WMEnableIWLEvent for details). Window state
that is monitored includes
- whether or not images are displayed
- the currently displayed section
- the assignment of particular wavelengths to particular colors for
image display
- the size and arrangement of the rectangular grid of images displayed
- the zoom factor for displayed images
- changes to whether or not images are displayed
- the position of the displayed image relative to the image window
boundaries
- the image scaling for the currently displayed section
- how complex data values are displayed
- something overwrites the image window with a new data set or deletes
the image window
If you no longer want the WM library to call a routine in response to an
image window change, call
WMCancelEventHandler.
C Prototype
#include "WMInclude.h"
int WMProcDisplayChange(int istream, int (*func)(), int argu);
Fortran Prototype
integer function WMProcDisplayChange(istream, func, argu)
integer istream, func, argu
external func
Parameters
- istream
- (in) If istream is an
IM library stream number associated with an
open image window (via either IMOpen or
IWAttachWin), the routine
registered will be called for changes to that image window. If
istream is less than zero, the routine registered will be
called for changes to any image window.
- func
- (in) Is the routine that the WM library will call
when the window specified by istream changes. When the
WM library calls func, it will pass it two arguments. The
first is the value of argu (an integer if WMAddEventHandler
is called from C or a reference to an integer if WMAddEventHandler is
called from Fortran). If WMAddEventHandler was called from C, the second
argument is the address of an XEvent structure describing the change.
The IW_CM_WIN_ID (defined in IWInclude.h) element of the xclient.data.s
field in the structure holds the window number of the window that changed
and the IW_CM_CHANGE_OR_SYN (defined in IWInclude.h) element of the
xclient.data.s field holds a constant that describes the type of change.
Those constants currently are:
- IW_WIN_KILLED
- The image window was overwritten with a new data
set or deleted.
- IW_BANK_DISPLAY_CHANGED
- A change not covered by IW_WIN_KILLED
occurred.
If WMAddEventHandler was called from Fortran, the second argument is
an integer equal to either IW_WIN_KILLED or IW_BANK_DISPLAY_CHANGED
which have the same meaning as in C. Currently, no Fortran include file
defines IW_WIN_KILLED or IW_BANK_DISPLAY_CHANGED: Fortran applications
will have to use their numeric equivalents, 681 for IW_WIN_KILLED and 690
for IW_BANK_DISPLAY_CHANGED. The WM library expects func to
return an integer, but the particular value returned has no effect on the
behavior of the library. If func has already been registered
for the same image window and that registration was not subsequently
canceled, the library will not reregister the function (i.e. call it
twice when a change notification is received) for the same image window.
- argu
- (in) The WM library will pass argu as the
first argument when it calls the registered routine, func.
Return Value
Returns negative one if communication with the image window system could
not be established, if istream is zero or is positive but not
attached to an image window the application has open, or if a memory
allocation error occurred while attempting to register the routine as an
event handler. Otherwise, returns one.
Overview
Undoes the effect of a prior call or calls to
WMProcDisplayChange. WMCancelDisplayChange
either cancels all registered handlers for image window changes
or cancels the registered handler of image window changes for a particular
image window.
C Prototype
#include "WMInclude.h"
int WMCancelDisplayChange(int istream);
Fortran Prototype
integer function WMCancelDisplayChange(istream)
integer istream
Parameters
- istream
- (in) If istream is an
IM library stream number associated with an
open image window (via either IMOpen or
IWAttachWin), WMCancelDisplayChange
will remove the routine, if any, registered for that window with
WMProcDisplayChange. If
istream is less than zero, WMCancelDisplayChange will remove
all the routines registered by
WMProcDisplayChange.
Return Value
Returns negative one if communication with the image window system could
not be established, if no event handlers have ever been registered,
or if istream is zero or is positive but not attached to an image
window the application has open. Otherwise, returns one.
Overview
By default, an application will only receive image window events for
the first mouse button if the application has
enabled image window events and
registered a routine to handle mouse button
events. Of the additional buttons, the image window traps the events from
buttons two through five and uses them as signals to change the currently
displayed section. By calling WMRegMouseButton for a button, you will
enable your application to receive image window events for that button
and, for buttons two through five, disable the normal image window behavior
in response to that button. When you are finished with the image window, you
must match the call to WMRegMouseButton with a call, for the same image window
and button, to WMUnRegMouseButton.
The mapping of button numbers to physical devices is usually configured
by the user for the computer system as a whole; below is a typical mapping:
- button one
- left mouse button
- button two
- middle mouse button
- button three
- right mouse button
- button four
- upwards motion of the mouse's scroll wheel
- button five
- downwards motion of the mouse's scroll wheel
C Prototype
#include "WMInclude.h"
int WMRegMouseButton(int istream, int button_num);
Fortran Prototype
integer function WMRegMouseButton(istream, button_num)
integer istream, button_num
Parameters
- istream
- (in) Is the IM library
stream number associated (via either
IMOpen or
IWAttachWin) with the target image
window.
- button_num
- (in) Is the index of the mouse button to affect.
Valid values of button_num range from one to five, inclusive.
Return Value
Returns negative one if istream is not currently attached to
an image window. Also returns negative one if button_num is less
than one or greater than five. Otherwise, returns one.
Overview
Prevents an application from receiving image window events for a particular
mouse button and image window, and if the application was the last one that
was receiving those events from that window, restores the default image window
behavior in response to that mouse button. Typically, you will call
WMUnRegMouseButton to undo the effects of a previous call to
WMRegMouseButton.
C Prototype
#include "WMInclude.h"
int WMUnRegMouseButton(int istream, int button_num);
Fortran Prototype
integer function WMUnRegMouseButton(istream, button_num)
integer istream, button_num
Parameters
- istream
- (in) Is the IM library
stream number associated (via either
IMOpen or
IWAttachWin) with the target image
window.
- button_num
- (in) Is the index of the button to affect.
Valid values of button_num range from one to five, inclusive.
Return Value
Returns negative one if istream is not currently attached to
an image window. Also returns negative one if button_num is less
than one or greater than five. Otherwise, returns one.
Remote Process Event Handling Functions
Overview
Registers a function that the WM library will call whenever the application
receives a remote input event of a particular type.
C Prototype
#include "WMInclude.h"
int WMAddInputEventHandler(int (*func)(), int ref, int argu);
Fortran Prototype
integer function WMAddInputEventHandler(func, ref, argu)
integer func, ref, argu
external func
Parameters
- func
- (in) Is the function that the WM library will call
when the application receives a remote input event of type ref.
The WM library will pass func two arguments. The first is the
size of the event, passed as an int if WMAddInputEventHandler was called
from C or as a reference to an integer if WMAddInputEventHandler was called
from Fortran. The second argument is the value of argu (i.e.
an integer if WMAddInputEventHandler was called from C or a reference to
an integer if WMAddInputEventHandler was called from Fortran). The WM
library expects func to return an integer, but the particular
value returned has no effect on the behavior of the WM library.
- ref
- (in) Specifies the type of remote input event that
will cause the WM library to call func.
- argu
- (in) When the WM library calls func,
it will pass argu as the second argument.
Return Value
If func is zero, returns zero; otherwise, returns the value of
ref.
Overview
Removes a handler, installed by
WMAddInputEventHandler, for remote
input events.
C Prototype
#include "WMRemFunc.h"
int WMCancelInputEventHandler(int handler_ref);
Fortran Prototype
integer function WMCancelInputEventHandler(handler_ref)
integer handler_ref
Parameters
- handler_ref
- (in) Specifies the type of remote events that
the application no longer wishes to handle.
Return Value
Returns one.
Overview
Initializes the mechanism for remote communication and starts the remote
process. Currently, WMStartRemoteProgram will not work unless the local
machine has a current Priism session to which the application calling
WMStartRemoteProgram can connect (i.e. the application and the Priism session
are running under the same user ID).
C Prototype
#include "WMRemFunc.h"
int WMStartRemoteProgram(const char* machine_name, const char* full_command);
Fortran Prototype
integer function WMStartRemoteProgram(machine_name, full_command)
character*(*) machine_name, full_command
Parameters
- machine_name
- (in) Is the host name for the remote machine.
- full_command
- (in) Is the shell command or commands to
execute on the remote machine.
Return Value
Returns one.
Overview
Sends data to a remote program.
C Prototype
#include "WMRemFunc.h"
int WMRemoteSendData(const void* data, int ref_id, int size);
Fortran Prototype
integer WMRemoteSendData(data, ref_id, size);
integer ref_id, size
application-specific type data(*)
Parameters
- data
- (in) Refers to the memory holding the data to be sent.
- ref_id
- (in) Is the type of the message sent and is used to
by the recipient to select a handler for the message.
- size
- (in) Specifies the number of bytes to send.
Return Value
Returns one.
Overview
Reads up to a given number of bytes from an incoming remote message. Does
not swap bytes in the incoming data.
C Prototype
#include "WMRemFunc.h"
int WMRemoteGetBytes(void* data, int size);
Fortran Prototype
integer function WMRemoteGetBytes(data, size)
integer size
application-specific type data(*)
Parameters
- data
- (out) Refers to the space to use for the incoming
data.
- size
- (in) Specifies the number of bytes to read.
Return Value
Returns the number of bytes read.
Overview
Reads up to a given number of two-byte chunks from an incoming remote
message and swaps bytes if the sending machine has a different byte ordering
than the recipient.
C Prototype
#include "WMRemFunc.h"
int WMRemoteGetInt2(void* data, int size);
Fortran Prototype
integer function WMRemoteGetInt2(data, size)
integer size
application-specific type data(*)
Parameters
- data
- (out) Refers to the space to use for the incoming
data.
- size
- (in) Specifies the number of two-byte chunks to read.
Return Value
Returns the number of two-byte chunks read.
Overview
Reads up to a given number of four-byte chunks from an incoming message and
swaps bytes if the sending machine has a different byte ordering than the
recipient.
C Prototype
#include "WMRemFunc.h"
int WMRemoteGetInt4(void* data, int size);
Fortran Prototype
integer function WMRemoteGetInt4(data, size)
integer size
application-specific type data(*)
Parameters
- data
- (out) Refers to the space to use for the incoming
data.
- size
- (in) Specifies the number of four-byte chunks to read.
Return Value
Returns the number of four-byte chunks read.
Window Manager Control Functions
Overview
Instructs the WM library to call a particular routine when the user
uses the window manager controls to close the dialog created with
WMInit. If you make multiple calls to
WMSetExitFunction, only the last has an effect.
If your application requires special actions to be taken when the program
exits, you should install a callback with WMSetExitFunction to perform those
actions in addition to any other method you provide the user for closing
the application. Otherwise, the user can force the application to exit
with the window manager controls and circumvent the actions that take place
when the application exits normally.
C Prototype
#include "WMInclude.h"
void WMSetExitFunction(int (*callback)());
Fortran Prototype
subroutine WMSetExitFunction(callback)
integer callback
external callback
Parameters
- callback
- (in) Is the routine the WM library will call in
response to the user using the window manager controls to close the
dialog created with WMInit. The WM library will
pass callback no arguments and expects callback to
return an integer value though the particular value returned has no
effect on the behavior of the library. When called from C,
callback may be zero to restore the default response (exiting
the application) to the user closing the main dialog with the window
manager controls.
Overview
Instructs the WM library to call a particular routine when the user
uses the window manager controls to close a dialog created with
WMInit or WMInitSubMenu.
If you make multiple calls to WMSetSubExitFunc for a particular dialog,
only the last has an effect.
C Prototype
#include "WMInclude.h"
void WMSetSubExitFunc(int menu_number, int (*callback)());
Fortran Prototype
subroutine WMSetSubExitFunc(menu_number, callback)
integer menu_number, callback
external callback
Parameters
- menu_number
- (in) Is the index for the dialog for which
close operations from the window manager will cause callback to
be called. menu_number can be zero, in which case
WMSetSubExitFunc will have the same effect as
WMSetSubExitFunction, or a value returned
by WMInitSubMenu.
- callback
- (in) Is the routine the WM library will call in
response to the user using the window manager controls to close the
dialog specified by menu_number. For dialogs other than
the main dialog (menu_number equal to zero), the library will
call callback after the dialog has been removed from the
display. The WM library will pass callback no arguments and
expects callback to return an integer value though the
particular value returned has no effect on the behavior of the library.
When called from C, callback may be zero to restore the
default response: exiting the application if menu_number is
zero or closing the dialog if menu_number is not zero.
Display/Dialog/Widget Information Functions
Overview
Determines the screen position of a dialog created with
WMInit or WMInitSubMenu.
As described here, WMGetLoc first appeared in the October 1999 release of
IVE 3.3. A different version, which lacked a return value and the
menunum argument, was included in the October 1998 release of
IVE 3.3.
C Prototype
#include "WMInclude.h"
int WMGetLoc(int* ix, int* iy, int menunum);
Fortran Prototype
integer function WMGetLoc(ix, iy, menunum)
integer ix, iy, menunum
Parameters
- ix
- (out) When WMGetLoc returns zero, WMGetLoc will set
the integer referred to by ix to the displacement, in pixels,
of the left edge of the dialog from the left edge of the screen. A
positive displacement means the left edge of the dialog is to the right of
the left edge of the screen.
- iy
- (out) When WMGetLoc returns zero, WMGetLoc will set
the integer referred to by iy to the displacement, in pixels,
of the top edge of the dialog from the top edge of the screen. A
positive displacement means the top edge of the dialog appears below the
top edge of the screen.
- menunum
- (in) Specifies the dialog of interest.
For a dialog created by WMInit, use a value of zero.
For a dialog created by WMInitSubMenu,
use the value returned by WMInitSubMenu.
Return Value
If the dialog specified by menunum has been initialized,
WMGetLoc returns zero and sets the integers referred to by ix and
iy. Otherwise, WMGetLoc returns negative one and does not
modify the integers referred to by ix and iy.
Overview
Determines the width and height, in pixels, for a dialog created with
WMInit or WMInitSubMenu.
The size of the dialog will be sensitive to the controls that have been
added to the dialog so you would normally call WMGetMenuSize after adding
all the controls to that dialog. WMGetMenuSize first appeared in IVE 4.0.7.
C Prototype
#include "WMInclude.h"
int WMGetMenuSize(int* width, int* height, int menunum);
Fortran Prototype
integer function WMGetMenuSize(width, height, menunum)
integer width, height, menunum
Parameters
- width
- (in) When WMGetMenuSize returns zero, WMGetMenuSize
will set the integer referred to by width to the width,
in pixels, of the dialog specified by menunum.
- height
- (in) When WMGetMenuSize returns zero, WMGetMenuSize
will set the integer referred to by height to the height,
in pixels, of the dialog specified by menunum.
- menunum
- (in) Specifies the dialog of interest.
For a dialog created by WMInit, use a value of zero.
For a dialog created by WMInitSubMenu,
use the value returned by WMInitSubMenu.
Return Value
If the dialog specified by menunum has been initialized,
WMGetMenuSize returns zero and modifies the values referred to by
width and height. Otherwise, WMGetMenuSize returns
negative one and does not modify the integer referred to by width
and height.
Overview
Determines the size of the default screen. A good use for
WMGetScreenSize is to use the result to determine where to place a dialog with
WMSetLoc.
WMGetScreenSize was added in IVE 4.0.7.
C Prototype
#include "WMInclude.h"
int WMGetScreenSize(int* width, int* height);
Fortran Prototype
integer function WMGetScreenSize(width, height)
integer width, height
Parameters
- width
- (out) If WMGetScreenSize returns zero,
WMGetScreenSize sets the integer referred to by width to
the width, in pixels, of the default screen.
- height
- (out) If WMGetScreenSize returns zero,
WMGetScreenSize sets the integer referred to by height to
the height, in pixels, of the default screen.
Return Value
Returns negative one if the WM library has not been initialized yet
(using WMInit, for example). Otherwise, returns zero.
Overview
Returns the number of bit planes in the overlay plane, if any, that the WM
library can use (see the documentation of
WMSetOverlayUse for how to place dialogs in
the overlay plane). If the WM library will not use an overlay plane because
of hardware or software limitations, WMOverlayDepth will return zero. The
number of colors available in the overlay plane is two raised to the number of
bit planes minus one. One of those colors typically can not be modified and
is used for the parts of the overlay plane that do not obscure the normal
display planes.
WMSetOverlayUse was added to Priism 3.3 in January 1999.
C Prototype
#include "WMInclude.h"
int WMOverlayDepth(void);
Fortran Prototype
integer function WMOverlayDepth()
Return Value
Returns the number of bit planes in the overlay plane used by the WM
library.