(*
 * Title:   menu.h
 * Purpose: Menu creation/deletion/manipulation.
 *
 *)

# ifndef __menu_h
# define __menu_h


type menu__str = record end;
     menu_ptr = ^menu;
     menu = ^menu__str;     (* abstract menu handle *)

(*
 * A menu description string defines a sequence of entries, with the
 * following syntax (curly brakets mean 0 or more, square brackets mean
 * 0 or 1):
 *    opt ::= "!" or "~" or ">" or " "
 *    sep ::= "," or "|"
 *    l1 ::= any char but opt or sep
 *    l2 ::= any char but sep
 *    name ::= l1 <open brace> l2 <close brace>
 *    entry ::= <open brace> opt <close brace> name
 *    descr ::= entry <open brace> sep entry <close brace>
 * Each entry defines a single entry in the menu. "|" as a separator means
 * that there should be a gap or line between these menu components.
 *
 *   opt ! means, put a tick by it
 *   opt ~ means, make it non-pickable
 *   opt > means, has a dialogue box as "submenu"
 *   space has no effect as an opt.
 *)


(* ----------------------------- menu_new ----------------------------------
 * Description:   Creates a new menu structure, from the given textual
 *                description (arranged as above).
 *
 * Parameters:    char *name -- name to appear in "title" of menu
 *                char *description -- textual description of menu
 * Returns:       pointer to menu structure created
 * Other Info:    creates menu structure, with entries as given in textual
 *                description. Entries are indexed from 1.
 *                         eg. m=menu_new("Edit", ">Info Create Quit");
 *                Handler needs to be attached using event_attachmenu.
 *
 *)
function menu_new(name : string; description : string) : menu; extern;


(* ------------------------------- menu_dispose ----------------------------
 * Description:   Disposes of a menu structure.
 *
 * Parameters:    menu* -- the menu to be disposed of
 *                int recursive -- non-zero ==recursively dispose of submenus
 * Returns:       void.
 * Other Info:    none.
 *
 *)
procedure menu_dispose(mp : menu_ptr; recursive : integer); extern;


(* ---------------------------- menu_extend --------------------------------
 * Description:   Adds entries to the end of a menu
 *
 * Parameters:    menu -- the menu to which extension is being made
 *                char *description -- textual description of extension.
 * Returns:       void.
 * Other Info:    extension has the format:
 *                        [sep] entry <open brace> sep entry <close brace>
 *                note: a menu which is already a submenu of another menu
 *                      can't be extended
 *
 *)
procedure menu_extend(m : menu; description : string); extern;


(* --------------------------- menu_setflags -------------------------------
 * Description:   Sets/changes flags on an already existing menu entry.
 *
 * Parameters:    menu -- the menu
 *                int entry -- index into menu entries (from 1)
 *                int tick -- non-zero == tick this entry
 *                int fade -- non-zero == fade this entry (ie. unpickable)
 * Returns:       void.
 * Other Info:    none.
 *
 *)
procedure menu_setflags(m : menu;
                entry : integer;
                tick, fade : boolean); extern;


(* ----------------------------- menu_submenu ------------------------------
 * Description:   Attaches a menu as a submenu of another at a given entry
 *                in the parent menu.
 *
 * Parameters:    menu -- the menu
 *                int entry -- entry at which to attach submenu
 *                menu submenu -- pointer to the submenu
 * Returns:       void.
 * Other Info:    This replaces any previous submenu at this entry. Use
 *                0 for submenu to remove an existing entry. Only a strict
 *                hierarchy is allowed. When attached as a submenu, a menu
 *                can't be extended or explicitly deleted.
 *
 *)
procedure menu_submenu(m : menu; entry : integer; submenu : menu); extern;


(* ------------------------- menu_make_writeable ---------------------------
 * Description:   Makes a particular menu entry writeable.
 *
 * Parameters:    menu m -- the menu
 *                int entry -- the entry to make writeable
 *                char *buffer -- pointer to buffer to hold text of entry
 *                int bufferlength -- size of buffer
 *                char *validstring -- pointer to validation string
 * Returns:       void.
 * Other Info:    Lifetimes of buffer and validstring must be long enough.
 *
 *)
procedure menu_make_writeable(m : menu;
                entry : integer;
                buffer : string;
                bufferlength : integer;
                validstring : string); extern;


(* --------------------------- menu_make_sprite ----------------------------
 * Description:   Makes a menu entry into a sprite.
 *
 * Parameters:    menu m -- the menu
 *                int entry -- entry to be made into sprite
 *                char *spritename -- name of the sprite
 * Returns:       void.
 * Other Info:    Entry which is initially a non-indirected text entry
 *                is changed to an indirected sprite, with sprite area given
 *                by resspr_area(), and name given by spritename.
 *
 *)
procedure menu_make_sprite(m : menu;
                entry : integer;
                spritename : string); extern;


(* ---------------------------- menu_syshandle -----------------------------
 * Description:   Gives low-level handle to a menu.
 *
 * Parameters:    menu -- the menu
 * Returns:       pointer to underlying WIMP menu structure.
 * Other Info:    allows massaging of menu other than provided in this 
 *                module. Returned pointer is in fact a pointer to a 
 *                wimp_menustr (ie wimp_menuhdr followed by zero or more
 *                wimp_menuitems).
 *
 *)
function menu_syshandle(m : menu) : pointer; extern;

# endif

(* end menu.h *)
