----- file created by makedoc on: Tue Mar  3 17:24:56 2009
----- Documentation for /scisoft/xop2.3/extensions/shadowvui/src/vui/xwmenu.pro -----

 NAME:
	XWMENU
 PURPOSE:
	This routine provides an editor for any IDL variable.
 CATEGORY:
	Widgets
 CALLING SEQUENCE:
	XWMENU, VAR
 INPUTS:
	VAR = The variable that is to be edited.
 KEYWORD PARAMETERS:
	NAME = The NAME of the variable.  This keyword is overwritten with the
		structure name if the variable is a structure.
	GROUP = The widget ID of the widget that calls XWMENU.  When this
		ID is specified, a death of the caller results in a death of
		XWMENU.

	The following keywords have been added at the ESRF in order to 
	use XWMENU for creating user-interfaces 

	NCOLUMN = number of column widget where to arrange the result
	NROW = number of row widget where to arrange the result
	ACTION = returns the string 'DO' or 'DONT' if the users exits
		with ACCEPT od CANCEL respectively.
	TITLES = (only works with structures) An array of strings
	 with dimension equals to the number of tags, containing
	 the titles of the tags to be displayed.
	NOTYPE  = (only works with structures) When set to 1, then do not
	 display the type of variable (string, float etc...)
	INTERP  = (only works with structures) When set to one, INTERprets
	 the tags which are defines as an array of strings as a pull-down
	 menu whose label shows the widget's current value. The possibles
	 value of the buttons are placed starting from the 1st index of
	 the string array. The 0-th index is kept for a string containing
	 the order of following elements to be display as defaul value.
	 The following example will create a window with 3 widgets, one
		with the title and the others with a pull-down menu, whereas
		the default values are 'a4' and 'b0' respectively.

		out	  =  { Stuct_name, $			; define
		TITLE: 'ESRF XWMENU test', $			; structure
		ITYPE: ['4','a0','a1','a2','a3','a4'] , $
		KTYPE: ['0','b0','b1','b2','b3','b4','b5'] }
		titles = [' This is the title: ', $
			'5 possible values of a',$		; set the
			'6 possible values of b']		; titles
		XWMENU,out,/interpret,titles=titles,/notype
	WTITLES = title for the main window.
	FIELDLEN = the size of the text fields (for structure input) in
		number of characters.
	HELP  = A string with either a string or string-vector.
		Depending on which one is chosen, the functionaly is different:
		1) A string is interpreted as a command to be executed. i.e. 
		   XWMENU,5,help="print,'socorro'" 
		   will print "socorro" on your terminal when "help" is pressed.
		2) A string-vector is interpreted as a text to be displayed. 
		   i.e. XWMENU,5,help=['help','me'] will open a window with 
		   a 2-lines text (help me) when pressing help.
		clicking on the "Help" button.
	SCROLL  = When set, forces scroll bar.
	W_SIZE  = [w_size_x,w_size_y] the window size in pixels. This 
		value is only used when the SCROLL keyword is set.
		Default: w_size = (tmp(0) * [5,5]) /9  where tmp is got from: 
		device, GET_SCREEN = tmp.
	APPLY_BUTTON  = When set to 1, creates a new button labelled "Apply".
		When pressed, the effect is the same that "Accept"
		except the ACTION keyword that is set to "DO_APPLY".
		This keyword can be used to simulate an "apply function"
		by the caller program. XWMENU is a modal widget that 
		cannot send events to the caller, but with the "Apply"
		button we can tell the caller that we want to recreate
		the XWMENU window. This action must be coded in the
		caller program.
		For example, a simple program to enter a number
		(norte the use of get/set_frame to force the XWMENU
		to sit at the same screen position).
		  PRO xnumber,i
		  action = ' '
		  frame=0
		  XWMENU,i,action=action,get_frame=frame,/apply_button
		  while action EQ 'DO_APPLY' do $
		   XWMENU,i,action=action,set_frame=frame,/apply_button
		  end
	GET_FRAME = Set this keyword to a named variable to get the
		Main XWMENU window offset (get_frame(0) and get_frame(1)) and 
		the window size (get_frame(2) and get_frame(3)).
		(Note: this is an approximate value, see comment in code)
	SET_FRAME = Set this keyword to 4-element array with:
		set_frame(0) the XOFFSET value for the main base window,
		set_frame(1) the YOFFSET value for the main base window,
		set_frame(2) the XSIZE value for the main base window,
		set_frame(3) the YSIZE value for the main base window.

 OUTPUTS:
	VAR= The variable that has been edited, or the original when the user
		selects the "Cancel" button in the editor.
 COMMON BLOCKS:
	Xvarcom1 - stores the base widget positions and dimensions
 SIDE EFFECTS:
	Initiates the XManager if it is not already running.
 RESTRICTIONS:
	If the variable is exceedingly large such as a giant structure or
	huge array, the editor will not fit on the screen and may not be able
	to create enough widget components to edit the whole variable.
 PROCEDURE:
	Create and register the widget and then exit.
	If the user selects "accept", the values in the editor are written
	to the variable passed in, otherwise, they are ignored.
 MODIFICATION HISTORY:
	Written by: Steve Richards,	February, 1991
	Nov 1993 M. Sanchez del Rio includes NROW , NCOLUMN , ACTION , 
		TITLES , NOTYPE and INTERPRET keywords
		for the ESRF applications. 
	94-02-14 MSR renames from Xvaredit [modified] to XscrMenu
	96-04-12 MSR automatic scrollbars when ntags > 15. Adds fieldlen kw
	96-11-13 MSR supresses the error message "Unable to convert given 
		STRING to Float". Includes xscrmenu_flags0 in xscrmenu.pro file.
	97-01-06 MSR adds the "help" button
	97-02-05 MSR adds automatic resizing.
	97-03-24 MSR adds SCROLL and W_SIZE keywords.
	97-08-26 MSR modified the HELP keyword, adds GET/SET_FRAME and 
		APPLY_BUTTON keywords.
	97-08-29 MSR adds frame_origin in common block to store the frame
		origin when apply button is pressed. This value is used to 
		create the next XScrMenu window at the same position.
	97-10-16 MSR fix a bug with get_frame (it didn't give the right
		result when the window was moved/resized by the user)
	97-11-07 MSR changes the windows dimension keyword when scroll
		is set: from scr_xsize to x_scroll_size (in windows the
		window didn't appear).
       97-11-10 Chr.Michetschlaeger, changes Common Blocks to Structure 
		(info),changes XSCRMENU2 for recursively calling
       97-11-12 CHM,adds Keywords to recursively callings 
       97-11-13 CHM,puts frame_origin as an Common Block, because of the 
		Apply_Button and the moving window action
       98-01-16 CHM,changed array treatment
       98-03-20 srio@esrf.fr renames to xwmenu, to keep the old
		xscrmenu alive!. The xwmenu code is very screw-up!
		The present routine has a big problem: it returns 
		all the structure tags converted to STRING type. 
	02-03-13 srio@esrf.fr str_sep substituted by strsplit

