PV-WAVE BUTTON MENU INTERFACE UTILITY
    $Id: README,v 1.2 1991/07/15 19:51:13 jeffry Exp $

Author:  TOYO INFORMATION SYSTEMS, INC.

********************
1.  INTRODUCTION
********************

This is a set of PV-WAVE utility routines to manage a high quality button 
interface without any toolkits provided for certain window systems.  Buttons 
are defined and grouped in a structure called a menu object.  This utility 
includes the features to define a new button in the menu object, change 
it, display it, and check if a button is selected, and so on.

For example, you could easily create a color, 3D-like display that looked
(much nicer than) the example below using this utility.
                _________________________________________________
		_________________________________________________
		|		         		        |
		|	 _________ 	_______________________	|
		|	|\_______/|     |                      ||  
                |       ||_FUNC1_||	|	               ||
                |       |/_______\|     |                      ||  
		|		        |                      ||
		|	 _________ 	|                      ||
		|	|\_______/|     |                      ||  
                |       ||_FUNC2_||	|	               ||
                |       |/_______\|     |                      ||  
                |                       |                      ||
		|	 _________ 	|                      ||
		|	|\_______/|     |                      ||  
                |       ||_EXIT__||	|	               ||
                |       |/_______\|     |                      ||  
                |                       |                      ||
                |                       |______________________||
		|_______________________________________________|

Here is the actual code to define the three buttons in the menu object:

	cols =	[10, 11, 255]
	obj =	Create_button (0, 1, 10, 300, 100, 20, cols, 'FUNC1')
	obj =	Create_button (obj, 2, 10, 200, 100, 20, cols, 'FUNC2')
	obj =	Create_button (obj, 999, 10, 10, 100, 20, cols, 'EXIT')
	Draw_button, obj

A menu object named "obj" with three buttons is defined and displayed on 
screen by the Draw_button procedure call.  Each button in the menu object has 
its own button number.  This example gives the button numbers 1, 2, and 999.

We can use the Pick_button procedure to pick a button from a menu object.  
Pick_button returns a button number if the specified coordinate position 
is on a button; otherwise, it returns -1.

	GET_POS:  Cursor,  x, y
	bno = Pick_button (obj, x, y)
	IF bno LT 0 THEN Goto, GET_POS
	IF bno EQ 999 THEN Goto, FINISH

You may want to change colors or from cubic to flat.  For these demands, 
there is a routine to change the definition of an individual button in the 
menu object.  The following example shows how to change the color of a 
picked button:

	bno = Pick_button (obj, x, y)
	IF bno GE 0 THEN
	  obj = Change_button (obj, bno, colors=[20, 21, 255])
	  Draw_button, obj, bno
	ENDIF

The Change_button procedure can redefine all of attributes used to define a 
button.  But the display is not automatically updated using new attributes.  
Especially when you want to change the position of a button, first you have 
to erase it from the screen and then you may redraw it using new 
attributes:

	Erase_button, obj, 2
	obj = Change_button (obj, 2, xpos=400, ypos=300)
	Draw_button, obj, 2


Here is a list of the routines in this utility:

 Create_button .........Define a new button in specified menu object.  
                        A new menu object will be created if it doesn't exist.

 Draw_button ...........Display a button or all buttons in the menu object.

 Pick_button ...........Check if a button is picked and returns its button 
                        number.

 Change_button .........Change the attributes of a button.

 Delete_button .........Delete a button or all buttons in the menu object.

 Erase_button ..........Erase a button or all buttons in the menu object.




*************************
2. FUNCTIONAL DESCRIPTION
*************************

The following form is used to describe each function.

	pro       procedure_name, parameter1, parameter2, ...

			or

	function  function_name (parameter1, parameter2,  ...)



	FUNCTION        :  Brief explanations ...

	ACCESS		:  Show how to access from WAVE level ...

			      *  The parameter(s) described in 
                                 [] can be omitted

	PARAMETERS	:  Name (type)  (I/0)  explanation  ...

        		      *  INT:Integer		STR:String		
                                 FLT:Floating point     ARR:Array
		            
                              *  I:Input only	   IO:Input/Output	
                                 O:Output only

	RETURN		:  Return value if it is a function ...

	KEYWORDS	:  Explanation of the keyword(s) ...

	EXAMPLE      	:  Simple example ...

	SUPPLEMENT	:  Additional information about this routine ...




________________________________________________________________________
function:  Create_button (menu_obj, bno, xp, yp, xsz, ysz, colors, label)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FUNCTION	  :  Define a new button in the menu object.

ACCESS            :  menu_obj = Create_button (menu_obj, bno, xp, yp, xsz, 
                     ysz, colors, label)

PARAMETERS    : menu_obj (---) (I) The menu object to which you want to add 
                                   a button (Specify 0 when you want to 
                                   create a new object).

		bno	(INT) (I)   A button number to define.  It should 
                                    be greater than or equal to zero.

                xp, yp  (INT) (I)   A device coordinate position of the 
                                    lower left corner of the button.
		
                xsz, ysz (INT) (I)  The width and height of the button 
                                    to be defined.

	        colors  (INTARR) (I) A two or three elements array to specify 
                                    colors of the button.  For a three element 
                                    array, the first element indicates the 
                                    basic color of the button, and the 
                                    second element indicates the color of 
                                    the shaded part, and the last element
                                    indicates the color of the label and 
                                    the edge between the top surface and the 
                                    shaded part.  For a two element array, 
                                    the first element indicates the basic 
                                    color and the second one indicates the 
                                    label color.  In this case, the button 
                                    seems to be flat.

	        label   (STRARR) (I) A label of the button.  You can specify 
                                    up to three labels using string array.  
                                    In this case, each line is automatically
                                    aligned to center position.

RETURN	: The new menu object structure is returned.

EXAMPLE	:

obj = Create_button (0, 1, 10, 300, 100, 20,  [1, 2, 255], 'BUTTON1')
obj = Create_button (obj, 2, 10, 200, 100, 20, [3, 4, 255], 'BUTTON2')


SUPPLEMENT:If you want to create a new menu object, specify 0 for first 
           parameter. If you specify an existing menu object to append a 
           new button and there already is a button which has the same 
           button number, an error message will be displayed.
				

			Basic Color
		__	____\__________
		|       |\   \        /|	   Label color
	ysz	|       | \__________/ |                 |
		|       |  | LABEL 1 --------------------|
		|       |  | LABEL 2 | |	
		|       | / -------- \ | <<Shaded part
		__      |/____________\|
                   ____/
		   |	|----- xsz ----|
		(xp,yp)




_______________________________
pro  Draw_button, menu_obj, bno
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FUNCTION      : Display a button or all buttons in the menu object.

ACCESS:       : Draw_button, menu_obj [, bno]

PARAMETERS    : menu_obj (--) (I) The menu object including the button you 
                                  want to display on screen.

	        bno	(INT) (I) The button number you want to display.  
                                  If you omit this parameter, all of buttons 
                                  in the menu object will be displayed.

EXAMPLE		: mobj = Create_button (0, 2, 10, 200, 100, 20, [3, 4, 255], 
                   'CONTINUE')
                  Draw_button, mobj

SUPPLEMENT	: You need to redisplay a button when you change attributes 
                  of the button by Change_button procedure.
 


________________________________________                
 function   Change_button (menu_obj, bno)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FUNCTION	: Change attributes of a button

ACCESS		: menu_obj = Change_button (menu_obj, bno)

PARAMETERS	: menu_obj (--) (I) The menu object including the button 
                                    you want to change.

       		  bno	  (INT) (I) The button number you want to change

RETURN		: Updated menu object is returned

KEYWORDS	: colors ........Change colors of the button 
                                 (See Create_button for detail).

		  xpos, ypos ....New position of the button in the device 
                                 coordinates

		  xsize, ysize ..New size of the button in the device 
                                 coordinates

		  label .........New label of the button.

EXAMPLE		: obj1 = Change_button (obj1, 2 colors=[3,9]
	          Draw_button, obj1, 2

SUPPLEMENT	: This function changes the contents of the menu object 
                  structure but does not reflect it on screen.  You should 
                  call Draw_button procedure to update the display.




______________________________________
function  Pick_button (menu_obj, x, y)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FUNCTION	: Check if a button is picked

ACCESS:		: bno = Pick_button (menu_obj, x, y)

PARAMETERS	: menu_obj (--) (I) The menu object which you want to check 
                                    if any button is picked.

		  x, y	  (INT) (I) A device coordinate position which you 
                                    want to test.

RETURN		: A button number is returned if the specified position is on 
                  any button in the menu object.  If no button is picked, -1 
                  is returned.

EXAMPLE		: Draw_button, mobj
		  Cursor, x, y, /device
	          bno = Pick_button (mobj, x, y)
		  IF bno GE 0 THEN BEGIN
		        mobj = Change_button (mobj, bno, color=[4,5])
		        Draw_button, mobj, bno	
                  ENDIF



________________________________
pro  Erase_button, menu_obj, bno
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FUNCTION	: Erase a button or all buttons in the menu object

ACCESS		: Erase_button, menu_obj [, bno]

PARAMETERS	: menu_obj  (--) (I)  The menu object which includes
                                      the button you want to 
                                      erase from screen.

		  bno      (INT) (I)  The button number you want to erase.  
                                      If you omit this, all buttons in the 
                                      menu object are erased.

KEYWORDS	: color ...By default, erasing is performed by polygon 
                           filling using background color.  When the 
                           button is displayed on an area filled with a 
                           different color, you may want to erase the 
                           button using it.

EXAMPLE		: Draw_button, mobj1
	          Cursor, x, y, /device
		  pick1 = Pick_button (mobj1, x, y)
	          Erase_button, mobj1
	          Draw_button, mobj2

SUPPLEMENT      : none




_______________________________________
Function   Delete_button (menu_obj, bno)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FUNCTION	: Delete a button or all buttons in the menu object

ACCESS		: menu_obj = Delete_button (menu_obj [, bno])

PARAMETERS	: menu_obj (--) (I)   The menu object which includes
                                      the button you want to delete.

		  bno     (INT) (I)   The button number you want to delete.  
                                      If you omit this the menu object 
                                      itself is deleted.

EXAMPLE		:  mobj = Delete_button (mobj, 3)

SUPPLEMENT	:  If you delete the menu object, this function
                   returns 0 (Integer scalar).
