KEYWORD grouping WMInit WMSetLoc WMDisplay WMInitSubMenu WMDisplaySubMenu WMUndisplaySubMenu WMAppMainLoop WMProcEvent WMNewRow WMSetOffset WMAddText WMAddFloatField WMAddIntField WMAddCharField WMAddToggleButton WMAddPulldown WMAddFuncButton WMAddInfoButton WMAddDoButton WMAddSaveButton WMAddScrolledText WMAddScrolledChoices WMAddGetFile WMAddFuncList WMAddHorSlider WMUnpasteWidget WMPasteWidget WMSensitiveGroup WMInsensitiveGroup WMUpdateGroup WMUpdateField WMUpdateFuncList WMForceUpdate WMConfirm WMConfirmError WMPostInfo WMAddArrowButton WMAddDrawingArea WMAddSeparator WMSliderShowValue WMAttachRightSide WMAddOnOffStatus WMDisableField WMEnableField WMRingBell WMEnableIWLEvent WMDisableIWLEvent WMAddEventHandler WMCancelEventHandler WMProcDisplayChange WMCancelDisplayChange WMProcClientMessage WMCancelClientMessage WMSetPulldownShowChoice WMSetGetFileSrc WMEnableGroup WMDisableGroup WMAddGLwMDrawWidget WMAddPulldownMenu WMAddOptionMenu WMNoTitleBar WMRetAppContext WMGetShellWidget WMSync WMRetLastButEvent WMGetLastButNum WMNotExecutable WMShowInfo WMRemoveInfo WMChangeText WMGetFile DESCRIPTION : WMMenu Library Calls The WMMenu Widget Library provides a simple means of incorporating a motif style Graphical User Interface (GUI) into your application programs. The major steps to creating 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 grouping The Widgets can be put into groups so that all widgets from one group can be updated when any one from that group is updated. Updating is done using a binary masking system, 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 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. 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 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 WMDisplay () This function is called after all the create widgets have been called to display the entire menu. 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 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 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 processes one event from the menu. 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 WMNewRow () Start next widget on new line 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 : a unique string descriptive of the program createing or accessing the file. char *patkey : ex. EditPolygon uses POLY_DIR for the dirkey and POLY_FILE_EXT for the patkey. 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 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 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 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 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 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 WMAddCharField Add a field to hold a character string. WMAddCharField (string, maxlen, dislen, callback, params, update, group) 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 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 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 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 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 in the help direcory. 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 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 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 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 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 WMGetFile(char *filename, char *dir, char *pattern, char *filter) Pops up the file selection menu as it comes to it in the code. no widget is created by this call. 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: 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. 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 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 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 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 WMUpdateFuncList (ilist, funcname, helpindex, nfunc, update) Replaces current function list with a new function list int ilist : Sometimes you may have more than one function list on your menu. ilist is the number of the function list you want to update. When each FuncList is created the function returns this reference number. 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 update : flag to indicate whether the content in "same group" fields should be updated after callback is executed. 0 = no, 1 = yes. 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 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. char *message : string holding the information to be confirmed WMConfirmError (message) Pops up a message to the user that an error has occured char *message : string holding the error message WMPostInfo (message, seconds) Pops up a message to the user to give any type of information. char *message : string containing message to be posted int seconds : number of seconds for the message to remain on the screen 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 WMAddDrawingArea (width,height) creates a widget that is a drawing area for Xt drawing int width,height : of the drawing area box 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 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 WMAttachRightSide () This stretches the widget last made before this call to the right side of the menu. 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 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. 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 WMEnableIWLEvent () This call must be made in order to recieve any events from the image window. WMDisableIWLEvent () turn off the recieving 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 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 WMProcClientMessage (function,argu) register function to call if a client message is recieved. int (*function()): callback function to call if recieve Client message int argu : pointer to arguments to pass to function WMCancelClientMessage () cancel the calling of the function earlier registered to be called whenever a client message is recieved. 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); 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); WMNoTitleBar() before createing a menu or submenu, use this call if you don't want a title bar on your menu 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. WMNotExecutable(filename) integer function returns 1 if the file is not executable char *filename: name of the file trying to use as an executable. WMShowInfo(message) Widget function pops up a message and leaves it up intil the WMRemove Info function is called. char *message: the message in the info popup 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 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 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 WMRetAppContext() XtAppContext function returns the context for the menu WMGetShellWidget() Widget function returns a shell widget WMSync() Flushes all the expose events that may be waiting in the event queue. 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.