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:
1. Initialize the menu with WMInit
2. Add Widgets
3. Display the menu with WMDisplay
4. Use WMAppMainLoop or WMProcEvent to get events
Example Program: Hello World
int end_program()
{
exit(0);
}
main()
{
int maxlen = 12;
int group = 1;
WMInit("Hello World Demo");
WMAddText ("Hello World", maxlen, group);
WMAddFuncButton("quit", end_program, NULL,
0, 0);
WMDisplay();
WMAppMainLoop();
}
This program creates a menu, containing a text widget that says "Hello World". Next to the Text Widget is a quit button. The menu will remain on the screen until the quit button is pushed, then the end_program routine will be called and the program ends.
I. Menu creationA call to WMInit creates the first menu. Other submenus can be created in the same program by calling WMInitSubMenu.
optional calls for creating menus
WMSetLoc sets the position of the menu on the screen.
WMNoTitleBar sets the next menu created to be created
without a title bar. WMOverrideRedirect - set the next
menu created to pop up even if the user has set in their
.Xdefaults file to use interactive placement of 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 independant 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
static char result_string[20];
int end_program()
{
exit(0);
}
int update_square(float *fvar)
{
float value, result;
value = *fvar;
result = value * value;
sprintf(result_string,"%f",result);
}
main()
{
float fvar = 0.0;
int maxlen = 10;
int dislen = 12;
int decimal = 2;
float min = 0;
float max = 0;
sprintf(result_string, "0.0000");
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();
}
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 FloatField, and writes the result to the result_ string which is reported by the WMAddText widget. The user can keep entering input and getting results until the function button to quit is pushed. Then the function end_program is called and the program ends.
1. Input Fields: are widgets that allow users to
type in information to the program. Notice that some parameters require
the address of a variable and others use a value.
WMAddCharField- holds a character string
WMAddFloatField - holds one or more floating point variables
WMAddIntField - holds one or more integer variables
2. Output fields: report current settings to user
but do not take any input from the user. Therefore they do not call callback
routines.
WMAddOnOffStatus - an indicator light to show status
WMAddText - shows one line of text
WMAddScrolledText - a scrollable widget to show multiple lines of text
WMAddStatusBar - a thermometer style bar for showing how far along
a process is.
3. Function Buttons - call a function after being
pushed by the user
WMAddArrowButton - creates an arrow in one of four directions
WMAddDoButton - starts an external program
WMAddFuncButton - just a button with a label
WMAddFuncList - shows a list of options to the user and calls the function
associated with the option
chosen.
WMAddInfoButton - used as a label and as a key to online help
WMAddSaveButton - saves all the parameters currently in the menu, creates
a restore button alongside the save button.
4. Selection
WMAddGetFile - a function button and character field combined to allow
users to either directly enter
a filename or pop up a file search and selection menu.
WMAddHorSlider- create a horizontal slider bar WMAddOptionMenu - create
a pulldown set of options
WMAddPulldown - create a single pulldown menu
WMAddPulldownMenu - create a cascade of menus
WMAddScrolledChoices - a scrolling set of options which lets the user
select an option by clicking on it.
WMAddToggleButton - create an on off toggle button
5. Drawing Areas
WMAddDrawingArea - create an area in your menu for drawing using Xt
and motif library calls.
WMAddGLwMDrawWidget - create 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 WMInsert, 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 effects.
The first widget added to the menu will be in the top left hand corner. Widgets added after that are added to the right side of the previous widget. To start a new row of widgets, there is a call WMNewRow which puts the next widget after that against the left side of the menu and below the other widgets. So the general order of widget creation is left to right and top to bottom. There are two other calls that are used in positioning of widgets . WMSetOffSet lets you specify the spacing between widgets. WMAttachRightSide extends the last widget created to the right side of the menu. Finally WMAddSeparator draws a horizontal line between two rows of widgets. Use it in place of WMNewRow if you want a line separating sections of the menu.
III. Menu Display In order to see the menu that's been created you have to make a display call.
WMDisplay will display the menu created by calling WMInit. WMDisplaySubMenu will display submenus created by WMInitSubMenu. and 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. The main menu can also be undisplayed with WMUndisplaySubmenu by using the number 0 as the function parameter.
IV. Processing Events The menuing 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 a 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 interupt. Then once in every loop cycle, you can make this call to check for an event.
V. Error and Info popups There are several window pop ups available to display special information to the user about what is currently happening in the program. WMConfirm is used to check with the user if what the program is about to do is ok. The user can respond ok or cancel, and the function will return the response back to the program so you can respond accordingly. WMConfirmError pops up a message to the user letting them know that there is some error in what they are trying to do so they can do it correctly. WMPostInfo lets the program give some information to the user such as some task is done.
VI. File Selection There is a file selection menu that can be popped up directly by calling WMGetFile or pops up when a user hits the GetFile button of the WMAddGetFile widget. This menu by default, will show the user thelist 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 the 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 theres 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. Everytime the user runs the program they will start in the directory currently associated with the key in the file, and if they end with a different directory, .ivestartup will be updated with the new settings. You can create a different key name for every program or every type of file.
VII. Monitor event handling WMMenu provides a way for your program to keep track of user interaction with the IVE monitor. This allows your program to handle tasks such as data picking and region selection in the image as well as updateing 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 the 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. WMRetLastButEvent returns the event structure of the last mouse event so that you can get extra event information. WMGetLastButNum returns which of the buttons was pushed in the last button press event.
VIII. Remote
Process Event Handling This set of calls lets you run and communicate
with a remote program from an interactive session. This provides a way
to make use of faster machines for data processing while viewing results
on a machine that can display the images with IVE.
The remote program can use regular imsubs calls to read and write to
your image windows. See the
documentation for IMOpen in
IM_ref2.html for a description of using imsubs from
a remote program.
In order for communication to work, both the session side program and remote program must call WMInit to initialize the event handling. The session side program starts up the remote program using the call WMStartRemoteProgram. After all callbacks are set up on both sides, WMProcEvent or WMAppMainLoop can be used to get the input events.
Callbacks are setup using the function WMAddInputEventHandler. Both the session program (prog1) and the remote program (prog2) can set up callback functions to receive information from the other side. Each WMAddInputEventHandler call registers a different function to be called upon receipt of an input event and associates the function with a reference id. A program can set up as many callback functions as it needs. Prog1 needs to know the prog2 reference ids and vise versa so that they can use these id's 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.
Menu Creation
WMInit
WMInitSubMenu
WMNoTitleBar
WMOverrideRedirect
WMSetLoc
WMSetOverlayUse
Widgets
WMAddArrowButton
WMAddOptionMenu
WMAddCharField
WMAddNestedPulldown
WMAddDoButton
WMAddPullRight
WMAddDrawingArea
WMAddPulldown
WMAddFloatField
WMSetPulldownShowChoice
WMAddFuncButton
WMAddPulldownMenu
WMAddFuncList
WMAddSaveButton
WMAddGetFile
WMAddScrolledChoices
WMAddGLwMDrawWidget
WMAddScrolledText
WMAddHorSlider
WMAddSeparator
WMSliderShowValue
WMAddStatusBar
WMAddInfoButton
WMAddText
WMAddIntField
WMAddToggleButton
WMAddOnOffStatus
Widget Modification
WMDisableField
WMUpdateGroup
WMEnableField
WMUpdateField
WMDisableGroup
WMChangePulldown
WMEnableGroup
WMChangeText
WMUnpasteWidget
WMChangeTitle
WMPasteWidget
WMInsertWidget
WMSensitiveGroup
WMEndInsert
WMInsensitiveGroup
WMDeleteWidget
Widget Positioning
WMAttachRightSide
WMNewRow
WMSetOffset
Menu Display
WMDisplay
WMDisplaySubMenu
WMUndisplaySubMenu
Processing Events
WMAppMainLoop
WMProcEvent
Error and Info Popups
WMConfirm
WMShowInfo
WMConfirmError
WMRemoveInfo
WMPostInfo
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
Dialog/Widget Information
WMGetLoc
WMOverlayDepth
Menu Creation
WMInit (title) Initializes the WMMenu library and creates a Motif form widget as the base of all the subsequently added widgets. This function must be called first when creating a menu.
integer function - returns zero :: this represents the first of possible submenus
char *title - a string for the title of the menu window
WMInitSubMenu (title) Initializes a submenu. An integer function that returns the number of the submenu created. WMInit returns the number zero, and every submenu created there after is numbered in order of creation.
char *title - a string for the title of the submenu window
WMNoTitleBar()before createing a menu or submenu, use this call if you don't want a title bar on your menu
WMOverrideRedirect( iflag ) set autoplacement on regardless of the setting in the users .Xdefaults file for interactive placement. Once set, all menus will be placed using the last setting until the setting is changed.
int iflag - 1 means override on, 0 means override off.
WMSetLoc (x, y) Defines the location of the menu on the screen.
int x : position of left edge of the window on the screen int y : position of the top edge of the window on the screen
WMSetOverlayUse (iflag) Sets whether or not dialogs or pulldowns should be placed in the overlay planes. Because the overlay planes do not affect the normal planes, this can be used to avoid expensive redraws (for instance if the pulldown would obscure an image). Because the overlay planes have limited colors, are used by the window manager for some effects, and require extra overhead for handling multiple color tables, this function frequently has inconvenient side effects (especially when used with dialogs). For determining the number of colors available in the overlay planes used by the WM library, use the WMOverlayDepth function. This function was added in January 1999.
integer function - returns the previous setting of the flag which is either WM_OVERLAY_YES or WM_OVERLAY_NO.
int iflag : If WM_OVERLAY_YES, subsequent calls (until the next call to WMSetOverlayUse) to WMInit, WMInitSubMenu, WMConfirm, WMConfirmError, WMShowInfo, WMPostInfo, WMAddOptionMenu, WMAddPulldown, WMAddPulldownMenu, WMAddNestedPulldown, and WMAddPullRight will attempt to create widgets in the overlay planes. WM_OVERLAY_YES is ignored if the hardware doesn't support overlay planes. If iflag is WM_OVERLAY_NO (or any other value), those calls will create widgets with the default behavior: pulldowns are in the same planes as their parent widgets and dialogs are in the normal planes.
Widgets
WMAddArrowButton (dir,callback,param) create an arrow button facing up, down, left or right that will call a function when pushed.
int dir : direction of the arrow, where possible values are: WM_DOWN_ARROW,
WM_UP_ARROW, WM_LEFT_ARROW,WM_RIGHT_ARROW
int (*callback()) : pointer to the callback function
int param : pointer to arguments for callback function
WMAddCharField (string,
maxlen, dislen, callback, params, update, group)
Add a field to hold a character string.
char *string : pointer to an array of chars for receiving input string.The
size should be equal to maxlen.
int maxlen : the maximum length of the character string
int dislen : number of characters displayed on the screen
int (*callback()) : an integer function to be called when the character
string is changed
int *params : a pointer to the arguments for the callback function
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed.
int group : flag to indicate the group number this widget belongs to
WMAddDoButton (build_com,param,qcom,command) Starts execution of a program.
int (*build_com()) : an integer function to be called when button is
pushed. the function called builds a command file to run an executable
outside of this program.
int *param : this 1st argument passed to build_com
char *qcom: string holding the name of the queue to submit the job
to
char *command : a character string containing the name of the command
file to submit
WMAddDrawingArea (width,height) creates a widget that is a drawing area for Xt drawing
int width,height : of the drawing area box
WMAddFloatField (fptr, num, dislen, maxlen, min, max, decimal, callback, params, update, group) Add a field to hold one or more floats.
float *fptr : an array of float variables
int num : number of elements in the float array
int dislen : number of characters displayed on the screen
int maxlen : the maximum length of the char string representing the
entire array of float numbers since the November 2003 release of IVE3.3, this
parameter is ignored.
float *min, *max : range of the accepted value ; if max = min , no
range is imposed
int *decimal : number of decimal points displayed for each number
int (*callback()) : an integer function to be called when any value
in the array is changed
int *params : a pointer to a argument array for the callback function
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed.
int group : flag to indicate the group number this widget belongs to
WMAddFuncButton (label, callback, params, update, group) Connect a button to a specific function.
char *label : string containing the name of the function button
int (*callback()) : an integer function to be called when any value
in the array is changed
int *params : a pointer to a argument array for the callback function
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed.
int group : flag to indicate the group number this widget belongs to
WMAddFuncList (funcnames, helpindex, nfunc, width, height, ifunc, callback, params, update) Adds a widget with a scrolled list of function buttons which can be chosen with the mouse. Each function has a help box to describe what the function does.
char ** funcnames : list of strings containing function names
char ** helpindex : list of strings containing help on each function
int nfunc : number of strings in the funcname array int width : in
pixels of list:: value < = 0 gives a newline and list is the width of
the menu.
int height : in pixels: value < = 0 gives a default height of 100
int *ifunc : pointer to variable to hold the number of the chosen function
int (*callback()) : an integer function to be called when a function
is selected from the list
int *params : a pointer to a argument array for the callback function
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed. 0 = no, 1 = yes.
WMAddGetFile (label, dir, pattern, maxlen, dislen, filename, callback, params, update, group) Creates a widget to help the user open new files. Uses a directory name and a pattern to display possible files for the user to choose from. The user may also just type in the filename to the Widget.
char *label : the prompt for filename
char *dir : the name of a directory containing files for input
char *pattern : pattern of files to display for selection ex. *.dat
int maxlen : maximum length a file name can be int dislen : length
of filename area displayed
char *filename : name of variable that holds filename
void callback : name of function to be called int param : parameter
array to send to the function
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed. 0 = no, 1 = yes.
int group : a number to group fields together
WMAddGLwMDrawWidget(width, height, expose_callback, ex_param, input_callback, input_param, GLXContext *context)
creates a GLw drawing area. graphics can be drawn in this window using OpenGl. returns created widget.
int width: the width of the drawing area int height: the height of the
drawing area
int (*expose_callback): the name of the function to call in the case
of an expose event
int *expose_argu: pointer to argument to be passed to expose callback
int (* input_callback): the name of the function to be called whenever
there is mouse input in the glx window int *input_argu: pointer to argument
to be passed to input callback
GLXContext *context: pass the address of your GLXContext so that the
library can create it and pass it to you. so you have it for GLwDrawingAreaMakeCurrent(w,*cx);
WMAddHorSlider (label, width, min, max, ivar, scallback, params, dcallback, dparams, update, group) Adds a sliding bar widget.
char *label : String containing the label of the slider
int width : Width in pixels of the slider int min, max : Minimum and
Maximum values for the slider range
int *ivar : Current value of the slider bar int (*scallback()) : Function
called when you release the mouse from the slider
int *params : parameters passed to scallback
int (*dcallback()): Function called as slider is dragged through each
unit on the slider
int *dparams : parameters passed to dcallback
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed. 0 = no, 1 = yes.
int group : a number to group fields together
WMSliderShowValue (flag) Controls whether or not the current value will be shown on sliders created after this call.
int flag : flag = 1, means show value
WMAddInfoButton ( label, keyword) Creates a button that opens this help program and shows the help for the that specific item.
char *label : label that is written on the button
char *keyword : file and keyword to access. The file is taken to be
the part of the string up to the first space; if the file does not begin
with '/' then the standard IVE help directory is prepended to it. Either
'.html' or '.hlp' is appended to the file. The keyword is the part of the
string after the first space; if the keyword is not provided the 'DESCRIPTION'
section (for '.hlp' files) or the file without a specific anchor (for '.html'
files) is shown. NULL can be passed as the keyword in which case a message
about no help being available is displayed when the info button is pressed.
WMAddIntField (iptr, num, dislen, maxlen, min, max, factor, callback, params, update, group) Add a field to hold one or more integers.
int *iptr : an array of integer variables
int num : number of elements in the integer array
int dislen : number of characters displayed on the screen
int maxlen : the maximum length of the char string representing the
entire array of integer numbers; since the November 2003 release of IVE3.3, this
parameter is ignored.
int *min, *max : range of the accepted value ; if max = min , no range
is imposed
int *factor : number that changed variable must be a multiple of to
be acceptable
int (*callback()) : an integer function to be called when any value
in the array is changed
int *params : a pointer to a argument array for the callback function
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed.
int group : flag to indicate the group number this widget belongs to
WMAddOnOffStatus (label, ivar,group) Creates an indicator light to tell when something is on or off
char *label: label of toggle
int *ivar : pointer to variable that holds the on or off state
int group : flag to indicate widget group
WMAddOptionMenu(char **label, int nlabel, int *ichoice, int(*callback)(), XtPointer param, int update, int group) Widget function to create an option pulldown widget
char **label: list of labels for the options int nlabel: number of options
int *ichoice: pointer to variable to hold the selected option
int (*callback()): name of integer function to call upon selection
XtPointer param: pointer to parameter(s) to send to callback
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed.
int group : flag to indicate the group number this widget belongs to
WMAddNestedPulldown(Widget
ref, char *menu_name, int *itemTypes, char **label,
int nlabel, int *ichoice, int (*callback)(), int *param, int update,
int group)
Creates the top level of a pulldown menu cascade that together with
WMAddPullRight
can have multiple levels of menus coming off of it. Each pulldown menu
created will have
tear-off menu capability.
Widget ref: the parent widget to all the pulldowns in the cascade. to
create the cascade,
create the first pulldown by setting
ref to null. Use the widget returned from this
pulldown, then get the parent
of that widget and use that as the ref widget when
adding the rest of the pulldowns
to the cascade.
char *menu_name: title of the current pulldown
int *itemTypes: array of nlabel elements, with each element set to
0, 1, or 2.
0: means that the element
will be a choice and stop at the current level. If you have a
callback routine associated with this routine, it will be called on this
selection.
1: means that the element
will have a pullright menu coming off of it.
2: a horizontal separator
will be inserted at this position in the menu (support for the separator
was added in the June 1999 release).
char **label: list of entry labels for the pulldown
int nlabel: number of entrys
int *ichoice: pointer to variable that holds the selected entry number
int (*callback()): name of the integer function that will be called
when an item is selected int *param: pointer to parameters to be passed
to callback function
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed. 0 = no, 1 = yes.
int group : a number to group fields together
Example: Widget cascade,menu_bar;
cascade =WMAddNestedPulldown(NULL,"file",choice_list,4, &ichoice,callback,&ichoice,0,2);
menu_bar = XtParent(cascade);
WMAddNestedPulldown(menu_bar,"object",diff_list,13, &ichoice2,callback2,&ichoice2,0,2);
WMAddPullRight(Widget
ref, int element, int *itemTypes, char **label, int nlabel, int *ichoice,
int (*callback)(), XtPointer param, int update, int group) Creates
a pulldown menu that comes
off to the right of another pulldown menu. This function only works
with a pulldown created
by WMAddNestedPulldown or WMAddPullRight.
Widget ref: this is the widget of the pulldown menu that this menu will
be coming off of.
int element: the number of the element in the pulldown that this menu
will pullright from.
the elements start from 0, ie if the
pulldown has five elements they are numbered 0-4.
int *itemTypes: array of nlabel elements, with each element set to
0, 1, or 2 just as in
WMAddNestedPulldown, you
can choose which elements will be selections and which
will have another
menu coming off to the right of it. In this way, the levels of pullright
menus can continue
for as deep as you wish.
0: means that the element
will be a choice and stop at the current level. If you have a
callback routine associated with this routine, it will be called on this
selection.
1: means that the element
will have a pullright menu coming off of it.
2: means that the a horizontal
separator will be inserted at this position in the menu (added May 1999).
char **label : a list of strings containing the names of the choices
int nlabel : the number of choices in the pulldown menu
int *ichoice : pointer to the number of the item chosen, numbered 0
to N-1 from top to bottom
int (*callback()) : an integer function to be called when a choice
is selected from the pulldown menu
int *params : a pointer to an argument array for the callback function
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed.
int group : flag to indicate the group number this widget belongs to
WMAddPulldown (label, nlabel, ichoice, callback, params, update, group) Add a pulldown menu with nlabel choices. See WMPulldownShowChoice for the two ways the pulldown can be used.
char **label : a list of strings containing the names of the choices
int nlabel : the number of choices in the pulldown menu
int *ichoice : pointer to the number of the item chosen, numbered 0
to N from top to bottom
int (*callback()) : an integer function to be called when a choice
is selected from the pulldown menu
int *params : a pointer to an argument array for the callback function
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed.
int group : flag to indicate the group number this widget belongs to
WMSetPulldownShowChoice (flag) controls what will be shown at the top of pulldowns created after this call. The pulldown name or the current choice.
int flag : if flag set to 1, the top of the pulldown shows the current choice instead of a menu title
WMAddPulldownMenu(ref, menu_name, label, nlabel, ichoice, callback, param, update, group)
creates one pulldown menu that is part of a cascade of pulldowns
Widget ref: the parent widget to all the pulldowns in the cascade. to create the cascade, create the first pulldown by setting ref to null. Use the widget returned from this pulldown, then get the parent of that widget and use that as the ref widget when adding the rest of the pulldowns to the cascade.
char *menu_name: title of the current pulldown
char **label: list of entry labels for the pulldown
int nlabel: number of entrys
int *ichoice: pointer to variable that holds the selected entry number
int (*callback()): name of the integer function that will be called
when an item is selected XtPointer param: pointer to parameters to be passed
to callback function
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed. 0 = no, 1 = yes.
int group : a number to group fields together
Example: Widget cascade,menu_bar;
cascade =WMAddPulldownMenu(NULL,"file",choice_list,4, &ichoice,callback,&ichoice,0,2);
menu_bar = XtParent(cascade);
WMAddPulldownMenu(menu_bar,"object",diff_list,13, &ichoice2,callback2,&ichoice2,0,2);
WMAddSaveButton (filename) Add a button that will save all the values in the menu at the time the button is pushed. A restore button is also created beside the save button.
char *filename : the saved menu will be stored in this file
WMAddScrolledChoices (strings, num_items, num_visible, callback, params, group) Creates a scrolled list of choices. The user selects a choice by clicking the choice with the mouse.
char **strings : list of strings containing the names of the choices
int *num_items : pointer to the number of choices int num_visible :
how many lines in the scrolled window to show at one time
int (*callback()) : an integer function to be called when a choice
is selected
int *params : a pointer to an argument array for the callback function
int group : flag to indicate the group number this widget belongs to
WMAddScrolledText (string, nitem, nvis, group) Creates a widget that prints text in a scrolled area. This cannot be typed into by the user.
char *string : a character array to hold one line of text
int *nitem : pointer to total number of lines to be scrolled
int nvis : number of lines visible at one time
int group : flag to indicate the group number this widget belongs to
WMAddSeparator() Widget function creates a horizontal line all the way across the menu to separate widgets above and below it. Multiple separators can be used to create a thicker line.
WMAddStatusBar(label, width, maxval, ivar, update, group) creates a thermometer style widget for showing how far along the program is in completeing a task. The widget needs to be updated periodically with a value representing the fraction complete.
char *label - a string to be shown just below the bar as a label int
width - width of the widget in pixels int maxval - this value will set
a range for the thermometer status bar. the range will be between zero
and maxval.
int *ivar - pointer to the variable that will be updated to show the
current status. This number should always be a number between zero and
the maxval.
int update : flag to indicate whether the content in "same group" fields
should be updated after this widget is updated. 0 = no, 1 = yes.
int group : a number to associated this widget with a group
WMAddText ( string, maxlen, group) Add an output only text widget. This widget does not expect any input from the user.
char *string : a character array to hold one line of text int maxlen : maximum number of characters that could be displayed int group : flag to indicate the group number this widget belongs to
WMAddToggleButton (label, ivar, callback, params, update, group) Add a widget to toggle between two settings.
char *label : a character array holding the label on the button
int *ivar : pointer to variable that holds the toggle state
int (*callback()) : function called when toggle switched
int *params : array of parameters to pass to the function
int update : flag to indicate whether the content in "same group" fields
should be updated after callback is executed.
int group : flag to indicate the group number this widget belongs to
Widget Modification
WMDisableField (w) temporarily disable field from user input
Widget w: the widget to disable. Each function that creates a widget returns the widget.
WMEnableField (w) enable field again after previously being disabled
Widget w: the widget number enable. a widget is returned by each function that creates a widget.
WMEnableGroup(group) Makes all the widgets in the group sensitive to user input.
int group : group number
WMDisableGroup(group) Disables all widgets in this group making them dimmed and non responsive to any user input.
int group : group number
WMUnpasteWidget (w1) Undisplays one of the Widgets from the menu.
Widget w1 : the widget returned on creation. Each function that creates a widget returns that widget. ex. w1 = WMAddIntField
WMPasteWidget (w1) Redisplays the undisplayed widget to the menu.
Widget w1: the widget returned on creation. Each function that creates a widget returns that widget. ex. w1 = WMAddIntField
WMSensitiveGroup (group) Makes all the widgets in the group sensitive to user input. ( same thing as WMEnableGroup )
int group : group number
WMInsensitiveGroup (group) Disables all widgets in this group making them dimmed and non responsive to any user input. ( same thing as WMDisableGroup )
int group : group number
WMUpdateGroup (group) Updates all of the widgets in the group.
int group : the number of the group to be updated
WMUpdateField (w1) Updates a single widget
Widget w1 : the widget returned on creation. Each function that creates a widget returns that widget. ex. w1 = WMAddIntField
WMChangePulldown (Widget
widget, char **new_labels, int *sens_list, int nlabel)
Used to change the labels on the choices of pulldown menus. Also lets
you set individual
choices of the pulldown to sensitive or insensitive. Can be used for
all pulldown types.
Widget widget: the widget that was returned from the pulldown creation
call.
char **new_labels: the list of new strings that will be used for all
the choices in the pulldown
int *sens_list: array of zeros or ones indicating whether each choice
in the pulldown should
be sensitive or insensitive.
int nlabel: tells how many elements will be in the sens_list and new_labels
arrays.
WMChangeText(widget,new_string) integer function to change the label on widgets such as info button,function button,etc.
Widget widget: the widget to be changed char *new_string: the new label for the widget
WMChangeTitle(widget, new_string) changes the title on the slider and the status bar
Widget widget: the widget to change char *new_string: the new title for the widget
WMForceUpdate (w1) Sometimes it is unpredictable when an update will actually be carried out. WMForceUpdate will make sure that the update will occur immediately.
Widget w1 : the widget returned on creation. Each function that creates a widget return that widget. ex. w1 = WMAddIntField
WMInsertWidget(Widget
w, int method) - Lets you specify a position in an existing menu
to insert new widget(s). After one insert call, you can add as many
widgets as you want including
calls to WMNewRow and when you are done inserting, call WMEndInsert.
Widget w: the existing widget in the menu that you want to insert after
int method: there are three possible ways to insert widgets.
method 0: insert new widget(s) to the right
of the specified widget
method 1: insert new widget(s) starting on
the next line after the specified widget and if you
inserted between two widgets on the same line, the next widget will
follow the new widgets
on the right side of it.
method 2: insert new widget(s) on it's own
line, continuing with the other existing widgets
on the next line.
WMEndInsert(int resize_flag)
- this must be called when you are finished an insert.
int resize_flag: 1 if you want
the menu to be resized at the end of the insert
0 if you do not
WMDeleteWidget(Widget
w, int resize flag) - delete a widget moving widgets that were
to the right of it and below it,
to close the gap created by the delete.
Widget w: the widget that you
want to remove
int resize_flag: 1 if you
want the menu to be resized at the end of the insert
0 if you do not
Widget Positioning
WMAttachRightSide () This stretches the widget last made before this call to the right side of the menu.
WMNewRow () Start next widget on new line
WMSetOffset (left, right, top, bottom) Defines the separation of each widget from others
int left : distance of left edge of widget from other widgets
int right : distance of right edge from other widgets
int top : distance of top edge from other widgets
int bottom : distance of bottm edge from other widgets
Menu Display
WMDisplay () This function is called after all the create widgets have been called to display the entire menu.
WMDisplaySubMenu (w) Displays the submenu after all the widgets have been created. Also use this function to redisplay a menu after a previous call to WMUndisplaySubMenu.
int w: the menu number, created when menu created with WMInitSubMenu.
WMUndisplaySubMenu (w) Hides a menu. The menu will still exist and can be redisplayed with WMDisplaySubMenu.
int w : the menu number, created when menu created with WMInitSubMenu
Processing Events
WMAppMainLoop () This function is called after WMDisplay to make the menu wait for and respond to user input. Use it when the menu runs the whole program.
WMProcEvent (wait) Use for more flexible use of the menu. A single call directly processes up to one event (invoked callbacks could cause processing of other events); the number of events directly processsed is returned.
int wait : flag to tell if you want to wait until an event occurs or just check to see if there is an event and process if so. wait = 0 ...... check for event wait = 1 ...... wait for event
Error and Info Pop Ups
WMConfirm (message) Pops up a message to the user to confirm that a that it's ok to do what it's about to do. 1 (which maps to true in C) is returned if the user selects ok; otherwise, 0 (false in C) is returned if the user chooses to cancel or closes the dialog via the window manager.
char *message : Is the string holding the information to be confirmed. To have the message displayed on multiple lines, imbed a newline character in message where you would like a line break (support for multiple line messages was added in the October 1999 release).
WMConfirmError (message) Pops up a message to the user that an error has occured
char *message : Is the string holding the error message. To have the message displayed on multiple lines, imbed a newline character in message where you would like a line break (support for multiple line messages was added in the October 1999 release).
WMPostInfo (message, seconds) Pops up a message to the user to give any type of information.
char *message : Is the string holding the message to be displayed. To have the message displayed on multiple lines, imbed a newline character in message where you would like a line break (support for multiple line messages was added in the October 1999 release). int seconds : number of seconds for the message to remain on the screen
WMShowInfo(message) Widget function pops up a message and leaves it up intil the WMRemove Info function is called.
char *message : Is the string to be displayed in the popup window. To have the message displayed on multiple lines, imbed a newline character in message where you would like a line break (support for multiple line messages was added in the October 1999 release).
WMRemoveInfo(widget) integer function removes the message popped up by WMShowInfo
Widget widget: the widget returned by the showinfo called which is now to be removed
WMRingBell (ivol,time) make the computer beep
int ivol : how loud the bell should be (-100 to 100) float time : number of seconds to ring bell
FileSelection
WMGetFile(char *filename, char *dir, char *pattern, char *filter) Invoking this function, displays a file selection dialog and waits for the user to select a file or cancel the operation. The function returns a value greater than zero if a file was selected; other values indicate that the dialog was closed without selecting a file. No permanent widget in the current dialog is created by this call: WMAddGetFile is one way to do that.
char *filename: array to hold the selected filename
The old method of file selection required passing in a directory a pattern and a filter. The new method which uses WMSetGetFileSrc makes these three parameters unnecessary. rather than mess up old code using these parameters we leave them in. just allocate these three arrays and pass them and then forget about them. char *dir: char *pattern: char *filter:
WMSetGetFileSrc(dirkey,patkey) In each users home directory should be a file called .ivestartup which holds (or will hold) the directory and file patterns keys matched with last used directorys and patterns respectively for as many programs as use this utility. Before using WMGetFile or WMAddGetFile, set the currently directory key and pattern key so that the directory last used with this program will be opened to the user.
char *dirkey : is a unique string descriptive of the type of file for which to browse and is used to lookup the last directory used for that type of file. char *patkey : another unique string used to lookup the file pattern last used for the file type. The table below lists common Priism file types and the dirkey and patkey arguments used for them.
| Data type | dirkey | patkey |
| MRC image | "IVE_DEF_DIR:" | "IVE_DEF_FILE_EXT:" |
| TIFF image | "TIFF_DIR:" | "TIFF_FILE_EXT:" |
| 2D Plot file | "PLOT_DIR:" | "PLOT_FILE_EXT:" |
| Polygons | "POLY_DIR:" | "POLY_FILE_EXT:" |
| Volume builder association list (old format) | "BLD_DIR:" | "BLD_FILE_EXT:" |
| Pick Points point list (old format) | "PICK_DIR" | "PICK_FILE_EXT:" |
| Model for 3D Model | "MOD_DIR:" | "MOD_FILE_EXT:" |
| Graphic colors description | "COLOR_DIR:" | "COLOR_FILE_EXT:" |
| PostScript output | "PSFILE_DIR:" | "PSFILE_EXT:" |
Monitor Event Handling
WMEnableIWLEvent () This call must be made in order to recieve any events from the image window.
WMDisableIWLEvent () turn off the receiving of events from image window.
WMAddEventHandler
(istream,mask,function,argu) Register a function to be called whenever
there is a window event. Register with one of the following masks.
ButtonPressMask
ButtonReleaseMask
EnterWindowMask
LeaveWindowMask
PointerMotionMask
KeyPressMask
KeyReleaseMask
int isteam : the number of the istream assoc. with image window
long mask : the specific event type to register
int (*function()) : pointer to callback function
int argu : pointer to arguments to pass to callback function
WMCancelEventHandler
(istream,mask) to cancel the calling of the function earlier registered
to be called whenever recieving one of these events.
ButtonPressMask
ButtonReleaseMask
EnterWindowMask
LeaveWindowMask
PointerMotionMask
KeyPressMask
KeyRelease Mask
int istream : the number of the stream assoc with image window
long mask : the specific event type
WMProcDisplayChange (istream,function,argu) Register a function to be called whenever there is a diplaychange event in the image window. ie. change section,wave,time,zoom,pan,resize.
int istream : the number of the stream assoc with image window
int (*function()) : callback function to call if there is a display
change in window
int argu : pointer to arguments to pass to function
WMCancelDisplayChange (istream) to cancel the calling of the function earlier registerd to be called whenever recieving a displaychange event.
int istream : the number of the stream assoc with image window
WMRegMouseButton (istream, button_mask) By default, the Monitor uses the middle and right mouse buttons for moving between sections and an application will not receive notification of those events. Use WMRegMouse button to turn off the Monitor's handling of the other two mouse buttons and enable the application to receive the events associated with those buttons.
int istream : the number of the stream attached to the image window
int button_mask : the button for which the application wants events.
Use zero for the left button, one for the middle button, and two for the
right button.
WMUnRegMouseButton (istream, button_mask) Restores the Monitor's handling for a mouse button. The application will no longer receive events for that button.
int istream : the number of the stream attached to the image window
int button_mask : the button for which the application does not want
events. Use zero for the left button, one for the middle button, and two
for the right button.
WMRetLastButEvent() XEvent function returns the last event caused by clicking the mouse.
WMGetLastButNum()
integer function returns 1,2 or 3 for the last mouse button clicked.
Remote Process Event Handling
WMAddInputEventHandler(int
(*function)(), int ref_id, int argu)
- registers a function to be called whenever
an input event with the corresponding
reference id is received.
int (*function()) : pointer to callback function
int ref_id : id to be used by WMRemoteSendData call to communicate
with this function
int argu : pointer to arguments to pass to callback function
WMCancelInputEventHandler(int
ref_id)
- unregisters the callback function associated with
this id by WMAddInputEventHandler
WMStartRemoteProgram
(char *machine_name, char *full_command)
- used by the interactive program to start the remote
program on the other machine.
char *machine_name: name of the remote machine
char *full_command: this command will be run from a shell script, on
*machine_name.
Include any commands and flags.
WMRemoteSendData(char
*data, int ref_id, int size)
- send data to a remote program
char *data: the pointer to the data being sent. data can be of any type
or combination
of types but the receiving function needs to know what to expect. Some
machines require that this pointer be cast to type (char *).
int ref_id: reference number to the function on the other program that
should be called
when this data is
received on the other side.
int size: the total size in bytes must be calculated for the chunk
of data being sent
WMRemoteGetBytes(char
*data, int size)
- receive byte data from a program on another
machine.
char *data: a character array to hold the incoming data
int size: the number of bytes to be read into the array
WMRemoteGetInt2(char
*data, int nget)
- receive short integer data from a program
on another machine
char *data: pointer to the short integer or short integer array to
hold the incoming two byte integer data. The pointer
should be cast to type (char *).
int nget: the number of two byte integers to be read from the remote
message
WMRemoteGetInt4(char
*data, int nget)
- receive 4 byte integer data or float data
from program on other machine
char *data: address of integer or float array big enough to hold the
incoming
data. The pointer should be cast to type(char *).
int nget: the number of four byte integers or floats to be read into
*data.
Window Manager Control - because users will often close a menu by double clicking the top left corner of the menu instead of using your quit button, it is a good idea to associate this method of quitting with your quit routine.
WMSetExitFunction(int (*callback)()) - instructs the WM library to invoke a function when the user uses the window manager controls to close the main dialog and exit the program.
int (*callback)(): the pointer to the function to be invoked
WMSetSubExitFunc(int menu_number, int (*callback)()) - instructs the WM library to invoke the function pointed to by callback when a given submenu is closed using the window manager controls.
int menu_number: the value returned by WMInitSubMenu or zero for the main dialog
int (*callback)(): the pointer to the function to be invoked
Dialog/Widget Information
WMGetLoc(int* pX, int* pY, int menuNumber) - determines the location of the specified dialog. If the dialog has been initialized, returns 0 and stores the location in the first two arguments; otherwise, returns -1 and does not modify the first two arguments. This function first appeared in the October 1998 release but did not take the menuNumber argument and did not return a value; the version as described here first appeared in the October 1999 release.