/* Copyright 1996 Acorn Computers Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/****************************************************************************
* This source file was written by Acorn Computers Limited. It is part of *
* the RISCOS library for writing applications in C for RISC OS. It may be *
* used freely in the creation of programs for Archimedes. It should be *
* used with Acorn's C Compiler Release 3 or later. *
* *
***************************************************************************/
/*
* Title: menu.h
* Purpose: Menu creation/deletion/manipulation.
*
*/
# ifndef __menu_h
# define __menu_h
typedef struct menu__str *menu; /* 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 {l2}
* entry ::= {opt} name
* descr ::= entry {sep entry}
* 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.
*
*/
menu menu_new(char *name, char *description);
/* ------------------------------- 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.
*
*/
void menu_dispose(menu*, int recursive);
/* ---------------------------- 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 {sep entry}
* note: a menu which is already a submenu of another menu
* can't be extended
*
*/
void menu_extend(menu, char *description);
/* --------------------------- 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.
*
*/
void menu_setflags(menu, int entry, int tick, int fade);
/* ----------------------------- 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.
*
*/
void menu_submenu(menu, int entry, menu submenu);
/* ------------------------- 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.
*
*/
void menu_make_writeable(menu m, int entry, char *buffer, int bufferlength,
char *validstring);
/* --------------------------- 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.
*
*/
void menu_make_sprite(menu m, int entry, char *spritename);
/* ---------------------------- 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).
*
*/
void *menu_syshandle(menu);
# endif
/* end menu.h */