/*
    ####             #    #     # #
    #   #            #    #       #          The FreeWare C library for 
    #   #  ##   ###  #  # #     # ###             RISC OS machines
    #   # #  # #     # #  #     # #  #   ___________________________________
    #   # ####  ###  ##   #     # #  #                                      
    #   # #        # # #  #     # #  #    Please refer to the accompanying
    ####   ### ####  #  # ##### # ###    documentation for conditions of use
    ________________________________________________________________________

    File:    Menu2.h
    Author:  Copyright  1995 Julian Smith
    Version: 1.00 (22 Jun 1995)
    Purpose: Easy menu handling
*/


#ifndef __dl_menu2_h
#define __dl_menu2_h

#ifdef __cplusplus
extern "C" {
#endif


#ifndef __dl_menu_h
#include "Menu.h"
#endif


/*
Menu2

Menu2 provides a slightly higher-level interface to menus than the
Menu library. It uses Menu functions. The application should
supply up to four functions for each menu it uses. These functions are
automatically called when required, to handle menu-choices, set
menuflags, find submenus, and generate custom menus.

The Menu2 library automatically handles the re-opening of menus after an
ADJUST choice, and also frees the menu data after a menu has closed.

If your app uses Menu2 then, when it starts up, it should call
Menu2_Create for every menu it will use, and store the returned
pointers.

These pointers are used to open menu in the future using Menu2_Open(),
or to specify what submenu should be opened when required.

Note that Menu2 only creates menus when they are actually open, in order
to save RMA memory.

There is also a function Menu2_AttachMenu which automatically opens
menus in response to a click on an icon/window.

*/


typedef int	menu2_handle;
/*
This type is used to identify menus.
*/

typedef menu_ptr	(*menu2_makefn)( void *reference);
/*
This function-type should make a menu and return a pointer to it.

'reference' is the reference originally passed to Menu2_Create for this
menu.
*/

typedef void		(*menu2_flagsfn)( menu_ptr menu, void *reference);
/*
This function-type should set any flags in the menu. It will be called
whenever the menu is created or reopened following an ADJUST
menu-choice.

'reference' is the reference originally passed to Menu2_Create for this
menu.
*/


typedef void		(*menu2_selectfn)( int itemnum, void *reference);
/*
This function-type is called whenever a menu-choice is made. 'itemnum'
determines the menu item-number which was chosen.

'reference' is the reference originally passed to Menu2_Create for this
menu.

Functions of this type shoule use globals such as event_lastevent and
menu_currentopen if they need to know more about the menu.

*/

typedef menu2_handle	(*menu2_subfn)( int itemnum, event_pollblock *event, void *reference);
/*
This function-type is called whenever a submenu is required. 'itemnum' is
the number of the menu item which needs a submenu, while 'event' is the
original message_MENUWARN.

'event' is included so that you can open a dialog box (or your own
submenu menu) using the information in the message_menuwarn
'event->data.message.data.menuwarn'. If this is done, the function
should return NULL, so that Menu2 knows that a submenu has been opened.

'reference' is the reference originally passed to Menu2_Create for this
menu.
*/






menu2_handle Menu2_Create( 
	char			*title,
	char			*spec,
	menu2_makefn		makefn,		/* If !=NULL, called to make the menu	*/
	menu2_flagsfn		flagsfn, 	/* Called every time menu is opened	*/
	menu2_subfn		subfn,		/* Called when submenu is needed	*/
	menu2_selectfn		selectfn, 	/* Called when selection is made	*/
	void			*reference	/* Passed to the 4 fns above		*/
	);
/*
This returns a unique handle for a menu.

Returns 0 if unable to make the menu - eg not enough memory.

If 'makefn' is NULL, the menu will be made, when required, from 'title'
and 'spec' using Menu_New. Otherwise, 'title' and 'spec' are ignored,
and the 'makefn' is relied apon to make the menu and return a pointer to
it.

NB 'title' and 'spec' are *not* copied, so they must point to permanent
strings.
*/



menu2_handle	Menu2_CreateFromMsgs(
			char		*titletag,
			char		*spectag,
			menu2_makefn	makefn,
			menu2_flagsfn	flagsfn,
			menu2_subfn	subfn,
			menu2_selectfn	selectfn,
			void		*reference
			);
/*
Same as Menu2_Create, except the title and menu specification are read
from a message file using Msgs_Lookup( titletag, ...) and Msgs_Lookup(
spectag, ...) .
*/


void	Menu2_Open( menu2_handle handle, int x, int y);
/*
This opens the specified menu. It uses Menu_Show, so use y=-1 if the
menu is an iconbar menu.
*/






void	Menu2_AttachMenu( 
	window_handle	window, 
	icon_handle	icon,
	menu2_handle	menu,
	int		button
	);
/*
This uses Event_Claim to open a menu when the specified icon-window is
clicked with the specified button(s). If the click is on the iconbar,
the menu will be automatically opened in the correct position for
iconbar menus.

Eg

Menu2_AttachMenu( w, i, specialmenu, button_MENU | button_SELECT);
Menu2_AttachMenu( w, event_ANY, generalmenu, button_MENU);

See also: Menu2_DetachMenu.
*/


void	Menu2_DetachMenu( 
	window_handle	window, 
	icon_handle	icon,
	menu2_handle	menu,
	int		button
	);
/*
Stops the specified menu being opened when the icon-window is clicked
with the specified button(s).

See also: Menu2_AttachMenu.
*/




#ifdef __cplusplus
}
#endif


#endif
