/******************************************************************************/
/* @(#)	popup.h	   1.0 -- standard include file for popup menu usage 09.07.88 */
/*									      */
/* This header file and the corresponding shared library are in the public    */
/* domain. They can be copied and distributed for non-commercial usage.       */
/*									      */
/* (c) 10/1987 by	Edgar Roeder					      */
/*			Liesbet-Dill-Str. 3				      */
/*			D-6602 Dudweiler				      */
/*			W-Germany					      */
/* 			E-mail: roeder@sbsvax.UUCP or			      */
/* 				roeder@eansb.informatik.uni-saarland.dbp&de   */
/******************************************************************************/

#define POPUP_LIB	"popup menus"
#define POPUP_VERSION	1

/*
 * usage of this package:
 *
 * menu_id = DefineMenu(str,args);
 * value = DoMenu(menu_id);
 * err = FreeMenu(menu_id);
 *
 * example:
 *
 * long	menu_id;
 * menu_id = DefineMenu(" testmenu %t| first | second | third ");
 * switch(DoMenu(menu_id)) {
 * 	case -2 : printf("Right mouse cancelled menu\n"); break;
 * 	case -1 : printf("No menu item selected\n"); break;
 * ...
 * }
 * if(FreeMenu(menu_id)) fprintf(stderr,"Cannot free this menu");
 *
 */

typedef long	menu;
typedef int	Value;

/******************************************************************************
 *                                                                            *
 * DefineMenu   returns a new menu id, which can be used to display the       *
 *              defined menu or 0 if an error occured                         *
 * DoMenu       returns as standard value the number of the selected item     *
 *              -2 is returned if the button is pressed outside the menu      *
 *              -1 is returned if no selection was made                       *
 *               0 is returned if there was an error                          *
 * FreeMenu     returns 0 if no error occured (menu_id is deleted)            *
 * ConfigRows   sets the maximum number of rows in a column (default is 5)    *
 *              and returns the old value for this                            *
 * ConfigScreen sets the border of the screen usable to display popup menus   *
 *              (the default values are: 0, 0, 639, 399 for mono screen)      *
 *                                                                            *
 *    complete definition of advanced menu formats (decreasing priority):     *
 *                                                                            *
 * format modifier |  required arguments  |          effect                   *
 * ----------------+----------------------+---------------------------------- *
 *       %t        | no additional args   | make a non selectable menu title  *
 * ----------------+----------------------+---------------------------------- *
 *       %v        | one int argument     | supply non standard return value  *
 *                 |                      |                                   *
 * ----------------+----------------------+---------------------------------- *
 *       %m        | one menu identifier  | invoke submenu                    *
 *                 |                      |                                   *
 * ----------------+----------------------+---------------------------------- *
 *       %c        | no additional args   | continue with menu if this item   *
 *                 |                      | is selected or no selection       *
 * ----------------+----------------------+---------------------------------- *
 *       %x        | no additional args   | continue with menu if no entry    *
 *                 |                      | selected                          *
 * ----------------+----------------------+---------------------------------- *
 *       %s        | no additional args   | selection required in this part   *
 * ----------------+----------------------+---------------------------------- *
 *       %o        | no additional args   | overlay this submenu (or all)     *
 * ----------------+----------------------+---------------------------------- *
 *       %f        | one function pointer | call function with standard       *
 *                 |                      | value as single argument          *
 * ----------------+----------------------+---------------------------------- *
 *       %h        | one function pointer | call function if user pressed     *
 *                 |                      | the Help key                      *
 *                                                                            *
 * if more than one format is given, the effects are occuring in order of     *
 * decreasing priority (you could attach a function to a whole menu with      *
 * %f and %m given in any order, or invoke the function with a non standard   *
 * value given with %v %f, in %m %v format the non standard value overrides   *
 * a return value of -1 if no selection occured during submenu invocation)    *
 *                                                                            *
 ******************************************************************************/

#ifdef LATTICE
extern Procedure *PopupLibBase;
#else
extern Library PopupLibBase;
#endif LATTICE

#ifdef POPUP_IMPLEMENTATION
extern menu	DefineMenu();	/* define a popup menu                        */
extern long	FreeMenu();	/* free the given menu                        */
extern Value	DoMenu();	/* display the given menu and handle input    */
extern int	ConfigMenu();	/* configure display parameters for defined   */
				/* menus				      */

/* this function is used by DoMenu with the actual mouse coordinates as input */
extern Value	DoXYMenu();	/* display menu at given coordinates          */
				/* usage: DoXYMenu(screen_handle,menu_id,x,y) */
#else
#define DefineMenu		(*PopupLibBase[0])
#define DoMenu			(*PopupLibBase[1])
#define FreeMenu		(*PopupLibBase[2])
#define DoXYMenu		(*PopupLibBase[3])
#define ConfigMenu		(*PopupLibBase[4])
#define ConfigRows(r)		ConfigMenu(r)
#define ConfigScreen(x,y,w,h)	ConfigMenu(0,x,y,w,h)
#define FormAlert		(*PopupLibBase[5])
#endif