Documentation from menu.h


Introduction	[top]

ROV - Easy applications from C

Copyright - © Jason Tribbeck / 7th ARM 1994-2001

Contributing authors - Jason Tribbeck

File - menu.h

Type - core

Description

The menu core system provides all the services for creating and displaying menus.


menu_list (type definition)	[top]

Structure of an item in a path of menus (for decoding menu clicks)
Parameters:
- i - the index in the menu (-1 for no more).
- m - the menu holding the index (0 for no more).
typedef struct {
  int i;
  menu m;
} menu_list;


_rov_menuh (function pointer)	[top]

Definition of a menu handler.
Parameters:
- menu m - the menu that was selected.
- int index - the index into the menu.
- menu_list menu_path - the path of opened menus from the top to the selected menu.
- int index_path - the index of items underneath the last attached menu (used for sub-menu creation).
Note - If submenus are not being used, then it is normally easier to use a simplified interface where the last two parameters are ignored.
typedef void (*_rov_menuh)(menu m,
			   int index,
			   menu_list menu_path[],
			   int index_path[]);


_rov_submenuh (function pointer)	[top]

Definition of a sub-menu handler.
Parameters:
- menu m - the menu that was selected.
- int index - the index into the menu.
- menu_list menu_path - the path of opened menus from the top to the selected menu.
typedef void (* _rov_submenuh)(menu m,
			       int index,
			       menu_list menu_path[]);


menu_create	[top]

Create a menu.
Parameters:
- char *title - the menu title.
- int max_items - the maximum number of items in this menu.
- ... - two parameters that are the functions for handling menu choices, and sub-menu creation.
Returns:
- the created menu.
Note - If a handler is not required, then NULL can be passed.
menu menu_create(char *title,
		 int max_items,
		 ...);


menu_init	[top]

Initialise the menu system.
Note - This must be done before menus are displayed.
void menu_init(void);


menu_add	[top]

Add an item to a menu.
Parameters:
- menu m - the menu.
- char *text - the text of the menu item.
Note - If the text is 12 characters or less in length, then the text is copied into the menu structure itself. If it is more than 12 characters, then the pointer is used.
void menu_add(menu m,
	      char *text);
See also: menu_addwriteable(), menu_changetext()


menu_clear	[top]

Zero the number of items in a menu.
Note - This differs from RISC_OSLib's menu_clear() function in that the ROV version does not free the memory.
void menu_clear(menu m);


menu_display	[top]

Display a menu.
Parameters:
- menu m - the menu.
Note - The position for this is taken from the mouse coordinates, with the x coordinate subtracted by 48, in accordance with the RISC OS Style Guide.
void menu_display(menu m);


menu_displaylocation	[top]

Display a menu at a given location.
Parameters:
- menu m - the menu.
- int x - the (screen) x coordinate.
- int y - the (screen) y coorinate.
void menu_displaylocation(menu m,
			  int x,
			  int y);


menu_displayiconbar	[top]

Display a menu from an icon on the icon bar.
Parameters:
- menu m - the menu.
Note - ROVLib calculates the correct y coordinate based on the number of items in the menu, and any splitters in the menu.
void menu_displayiconbar(menu m);


menu_addwriteable	[top]

Add a writeable menu item.
Parameters:
- menu m - the menu.
- char *buffer - the pointer to the buffer.
- char *valid - the validation string.
- int length - the maximum string length.
void menu_addwriteable(menu m,
		       char *buffer,
		       char *valid,
		       int length);
See also: menu_add()


menu_setfore	[top]

Set the foreground colour of a menu item.
Parameters:
- menu m - the menu.
- int index - the item index.
- int col - the WIMP colour.
Note - ROVLib will set the correct colour for you based on the Style Guide, but this allows you to override it (for example, the colourmenu helper does this).
void menu_setfore(menu m,
		  int index,
		  int col);
See also: colourmenu.h, menu_setback()


menu_setback	[top]

Set the background colour of a menu item.
Parameters:
- menu m - the menu.
- int index - the item index.
- int col - the WIMP colour.
Note - ROVLib will set the correct colour for you based on the Style Guide, but this allows you to override it (for example, the colourmenu helper does this).
void menu_setback(menu m,
		  int index,
		  int col);
See also: colourmenu.h, menu_setback()


menu_fade	[top]

Fade/unfade a menu item.
Parameters:
- menu m - the menu.
- int index - the item index.
- int fade - non-zero fades the menu item, zero unfades the item.
void menu_fade(menu m,
	       int index,
	       int fade);


menu_tick	[top]

Tick/untick a menu item.
Parameters:
- menu m - the menu.
- int index - the item index.
- int tick - non-zero ticks the menu item, zero unticks the item.
void menu_tick(menu m,
	       int index,
	       int tick);


menu_submenu	[top]

Attach a sub-menu to a menu.
Parameters:
- menu parent - the parent menu.
- int index - the index.
- menu child - the child menu.
void menu_submenu(menu parent,
		  int index,
		  menu child);


menu_attachpane	[top]

Attach a canvas to a menu.
Parameters:
- menu parent - the parent menu.
- int index - the index.
- canvas c - the canvas.
Note - This is typically used to put program information windows and file information windows into a menu structure.
Note - Clicking the canvas will not cause a call to the menu choose handler.
void menu_attachpane(menu parent,
		     int index,
		     canvas c);


menu_changetext	[top]

Change the text of a menu item.
Parameters:
- menu m - the menu.
- int index - the index.
- char *text - the new text.
void menu_changetext(menu m,
		     int index,
		     char *text);
See also: menu_add()


menu_split	[top]

Split at a point.
Parameters:
- menu m - the menu.
- int index - the index to split after.
- int split - non-zero to split, zero to remove split.
void menu_split(menu m,
		int index,
		int split);


menu_displaysubmenu	[top]

Display a sub-menu.
Parameters:
- menu m - the menu to display.
Note - This is called in a sub-menu handler to display the next level of menu.
void menu_displaysubmenu(menu m);


menu_displaysubcanvas	[top]

Display a canvas as a sub-menu.
Parameters:
- canvas c - the canvas to display
Note - This is called in a sub-menu handler to display a canvas as the next level of menu,
void menu_displaysubcanvas(canvas c);


menu_displaycanvas	[top]

Display a canvas using menu methods.
Parameters:
- canvas c - the canvas
void menu_displaycanvas(canvas c);


menu_subwarning	[top]

Make a menu item a sub menu with a warning.
Parameters:
- menu m - the menu.
- int index - the index.
Note - This will call the menu's sub menu warning handler.
void menu_subwarning(menu m,
		     int index);


menu_displayicon	[top]

Make a menu appear to the right of an icon.
Parameters:
- menu m - the menu.
- icon ic - the icon.
void menu_displayicon(menu m,
		      icon ic);


menu_displaycanvasicon	[top]

Make a canvas appear as a menu to the right of an icon.
Parameters:
- canvas c - the canvas.
- icon ic - the ico.
void menu_displaycanvasicon(canvas c,
			    icon ic);


menu_remove	[top]

Remove all menus from the screen.
void menu_remove(void);


menu_settitle	[top]

Set the title of a menu.
Parameters:
- menu m - the menu.
- char *title - the title.
void menu_settitle(menu m,
		   char *title);


menu_checkwidth	[top]

Ensure the width of a menu is correct.
Parameters:
- menu m - the menu.
void menu_checkwidth(menu m);


MENU_NULL (definition)	[top]

A null menu.

#define MENU_NULL ((menu)-1)

Generated Thu Feb 7 23:22:52 2002

Documentation from menu.h

Introduction

ROV - Easy applications from C

Description

menu_list (type definition)

_rov_menuh (function pointer)

_rov_submenuh (function pointer)

menu_create

menu_init

menu_add

menu_clear

menu_display

menu_displaylocation

menu_displayiconbar

menu_addwriteable

menu_setfore

menu_setback

menu_fade

menu_tick

menu_submenu

menu_attachpane

menu_changetext

menu_split

menu_displaysubmenu

menu_displaysubcanvas

menu_displaycanvas

menu_subwarning

menu_displayicon

menu_displaycanvasicon

menu_remove

menu_settitle

menu_checkwidth

MENU_NULL (definition)