$Id: README,v 1.3 1992/05/04 03:55:38 alan Exp $

This file briefly describes some widget utility procedures contributed
by Francois Briandet of the PVI Paris Professional Support Group.

PROGRAMS
pm_menu-ex.pro:
	Example for the use of pm_menu package

PROCEDURES

pm_activ_menu.pro:
 	Using a list given in argument, open a window and display
           a data input panel.
        Uses the following specific functions: pm_but_inlist,
            pm_button_menu,pm_help_menu and pm_proc_char.

FUNCTIONS

pm_build_menu.pro:
 	Build a list of records (input fields) to be used by the
           pm_activ_menu procedure

pm_read_menu.pro:
	Read the value gotten by pm_activ_menu and stored in the 
           given list . Optionnaly reset the default value

pm_but_inlist.pro:
 	Check if the x,y coordinate are included in one of the buttons
           given in the list.
        No user direct acces, only use with pm_activ_menu.

pm_button_menu.pro:
 	Display in the current window the given button , represented 
           in a specified state (up/down,slected/unslected).
        No user direct acces, only use with pm_activ_menu.

pm_help_menu.pro:
	Open a window and display all the information related to 
           the given menu record (number,default, min/max value)
           No user direct acces, only use with pm_activ_menu.

pm_plot_but.pro:
 	Process the cursor event loop and display refreshing for
           the plot control panel.
        No user direct acces, only use with pm_set_plot.

pm_proc_char.pro:
 	Process the edition of the current text record charcter by
           character.
        No user direct acces, only use with pm_activ_menu.


DATA ENTRY SCREEN CREATION
Using the ps_menu package


I Theory of Operation

 A Data entry screen consists of fields, viewed as labels or entry fields.
 We want to create a set of fields corresponding to the entry screen, then
 to display it and to allow the user the data entry.  We also want to retrieve
 that information.

 The set of fields is stored in a structure table, dynamically allocated 
 when fields are added.  Each field contains a label, an id number, a type
 the entry format, possible values, default values, and other information
 to maintain the field. This data will be passed to different functions.

 When the entry screen is displayed, the first field in the screen is
 active.  The user can change the default value of the field, or can enter
 a value.  S/he can then move to a different field, using either the arrows
 or the mouse.  The content of the current field can only be validated if the
 value is within the range of the field.  Otherwise, a help panel pops up,
 The corresponding field is then active, with a default value.  The entry
 validation is done by clicking the 'OK' button.

 For each field, the user can retrieve the entered value.

II Functions

 function PM_BUILD_MENU

 This function creates entry fields.  It will be used for each field.  It
 returns the set of fields defined in a set.

 Arguments:
   - menu_list: list of defined fields.  Must be set to 0 for the first field.
   - rec_no   : id number for the new field.
   - rec_type : type/format of the variable to enter.  It is not necessary to
	        supply a format.  However, the letter corresponding to the
	  	variable type must given.  The following types/formats are
		supported:
			'In'	: long integer (def: I11)
			'Fn.n'	: float		(def: F17.5)
			'Dn.n'	: double	(def: F20.8)
			'An'	: string	
			where n indicates the number of digits.
		N.B. integers are set to LONG's.

   ( The following arguments are optional)
   - label=	: field label (def: 'Record rec_no')
   - minv=	: minimum value (def: -2^21) (no meaning for a string )
   - maxv=	: maximum value (def:  2^21) (no meaning for a string )
   - defv=	: default value (def: 0 or '' for a string)

 Return:
   The function returns the list of defined field (menu_list),
   including the new field.

 Example:
	Build a field for a positive float defining a volume (no format)
	list = pm_build_menu(list, 1, 'f', label='Volume (l)', minv= 0.)


 procedure PM_ACTIVE_MENU

   This function displays the entry screen, and allows for data entry.

   In the active field, the cursor is marked with a '^' (upper carat)
   character.  The cursor can be moved using the left and right 
   arrow keys.  The [BACKSPACE] deletes the character left of the cursor
   Typing a new character will insert it right of the cursor.
   To switch field, you can either use the up and down arrow keys, or click
   with the mouse.  The validation buttons are activated with the mouse.


   Disclaimer:  Under Motif, the user must always click the right mouse button,
	to avoid blocking data entry.  Check that [BACKSPACE] echoes the(BS:8)
	ASCII code.

   Arguments:
	- menu_list	: list of defined fields.
		This function also returns the data entered.
	- exit_mode : defines with validating buttons to display.

 			0: 	1 button   :  'OK'
			1: 	2 buttons  : 'OK'+'Cancel'
			2: 	3 buttons  : 'OK'+'Cancel'+'Help'
    
          As a return value, contains the error code of the function
			-1:     ERROR
                         0:     OK
			 1:	CANCEL 

	(The following arguments are optional)
	- title=  : screen title 
                    (def: 'User menu')
	- xpos=,ypos= : screen coordinates of the bottom left corner.
                         (def: xpos=16,ypos=16)
        - font=       : WAVE font to use.
                        (def: font=3)
	- char_size=  : size of the fonts.
                        (def: char_size=1)
	- spacing=    :  number of lines between lines. (def: spacing = .5) 
	- backcolor=  :  background color (def: !D.N_COLORS/2)
    	- off_color=  :  non-active field colors.
    	- on_color=   :  active field colors.


 Function PM_READ_MENU

   To retrieve the data entered.  It resets the default value to the input
   value, unless otherwise specified.


   Arguments:

   - menu_list: list of defined fields.  Must be set to 0 for the first field.
   - rec_no   : id number for the field to read.

   (Optional argument)
   - /def      : indicates if the value by default must be kept.

   Return:
	The function returns the entered value in the field, of the type
	set for the field.


	(See also pm_menu-ex.pro to use these functions)

