/src/ui-menu.h

  1/*
  2 * Copyright (c) 2007 Pete Mack and others
  3 * This code released under the Gnu Public License. See www.fsf.org
  4 * for current GPL license details. Addition permission granted to
  5 * incorporate modifications in all Angband variants as defined in the
  6 * Angband variants FAQ. See rec.games.roguelike.angband for FAQ.
  7 */
  8
  9#ifndef INCLUDED_UI_MENU_H
 10#define INCLUDED_UI_MENU_H
 11
 12/* ============= Constants ============ */
 13
 14/* Colors for interactive menus */
 15enum
 16{
 17	CURS_UNKNOWN = 0,		/* Use gray; dark blue for cursor */
 18	CURS_KNOWN = 1			/* Use white; light blue for cursor */
 19};
 20
 21/* Cursor colours for different states */
 22extern const byte curs_attrs[2][2];
 23
 24/* Standard menu orderings */
 25extern const char lower_case[];			/* abc..z */
 26extern const char upper_case[];			/* ABC..Z */
 27
 28
 29
 30/* Forward declare */
 31/* RISC OS already has a menu_item in system library */
 32#ifdef RISCOS
 33#define menu_item ang_menu_item
 34#endif
 35
 36typedef struct menu_item menu_item;
 37typedef struct menu_type menu_type;
 38typedef struct menu_skin menu_skin;
 39typedef struct menu_iter menu_iter;
 40
 41
 42/* ================== MENUS ================= */
 43
 44/*
 45 * Performs an action on object with an optional environment label 
 46 * Member function of "menu_iter" VTAB
 47 */
 48typedef void (*action_f)(void *object, const char *name);
 49
 50/* 
 51 * Displays a single row in a menu
 52 * Driver function for populating a single menu row.
 53 * Member function for "menu_iter" VTAB
 54 */
 55typedef void (*display_row_f) (menu_type *menu, int pos,
 56			       bool cursor, int row, int col, int width);
 57
 58/* 
 59 * Driver function for displaying a page of rows.
 60 * Member function of "menu_skin" VTAB
 61 */
 62typedef void (*display_list_f)(menu_type *menu, int cursor, int *top, region *);
 63
 64
 65/* Primitive menu item with bound action */
 66typedef struct menu_action
 67{
 68	int id;			/* Object id used to define macros &c */
 69	const char *name;	/* Name of the action */
 70	action_f action;	/* Action to perform, if any */
 71	void *data;		/* Local environment for the action, if required */
 72} menu_action;
 73
 74
 75/* Decorated menu item with bound action */
 76struct menu_item
 77{
 78	menu_action act; /* Base type */
 79	char sel;        /* Character used for selection, if special-purpose */
 80	                 /* bindings are desired. */
 81	int flags;	 /* State of the menu item.  See menu flags below */
 82};
 83
 84
 85/* TODO: menu registry */
 86/*
 87  Together, these classes define the constant properties of
 88  the various menu classes.
 89
 90  A menu consists of:
 91   - menu_iter, which describes how to handle the type of "list" that's 
 92     being displayed as a menu
 93   - a menu_skin, which describes the layout of the menu on the screen.
 94   - various bits and bobs of other data (e.g. the actual list of entries)
 95 */
 96
 97
 98/* Flags for menu appearance & behavior */
 99/* ==================================== */
100
101/* Tags are associated with the view, not the element */
102#define MN_REL_TAGS 0x0100 
103/* No tags -- movement key and mouse browsing only */
104#define MN_NO_TAGS  0x0200 
105/* Tags to be generated by the display function */
106#define MN_PVT_TAGS  0x0400 
107/* Tag selections can be made regardless of the case of the key pressed. 
108 * i.e. 'a' activates the line tagged 'A'. */
109#define MN_CASELESS_TAGS 0x0800 
110
111/* double tap (or keypress) for selection; single tap is cursor movement */
112#define MN_DBL_TAP 0x1000 
113/* Do not invoke the specified action; menu selection only */
114#define MN_NO_ACT 0x2000 
115/* No cursor movement */
116#define MN_NO_CURSOR 0x8000 
117
118
119/* Row flags in action_menu structure. */
120#define MN_DISABLED   0x0100000 /* Neither action nor selection is permitted */
121#define MN_GRAYED     0x0200000 /* Row is displayed with CURS_UNKNOWN colors */
122#define MN_GREYED     0x0200000 /* Row is displayed with CURS_UNKNOWN colors */
123#define MN_SELECTED   0x0400000 /* Row is currently selected */
124#define MN_SELECTABLE 0x0800000 /* Row is permitted to be selected */
125#define MN_HIDDEN     0x1000000 /* Row is hidden, but may be selected via */
126                                /* key-binding.  */
127
128
129/** Identifier for the type of menu layout to use */
130typedef enum
131{
132	MN_SKIN_SCROLL = 1,   /**< Ordinary scrollable single-column list */
133	MN_SKIN_COLUMNS = 2   /**< Multicolumn view */
134} skin_id;
135
136
137/* Class functions for menu layout */
138struct menu_skin
139{
140	/* Determines the cursor index given a (mouse) location */
141	int (*get_cursor)(int row, int col, int n, int top, region *loc);
142	/* Displays the current list of visible menu items */
143	display_list_f display_list;
144	/* Specifies the relative menu item given the state of the menu */
145	char (*get_tag)(menu_type *menu, int pos);
146};
147
148
149/* Identifiers for canned row iterator implementations */
150typedef enum
151{
152	/* A simple list of actions with an associated name and id.
153	   An array of menu_action */
154	MN_ITER_ACTIONS = 1,
155
156	/* Slightly more sophisticated, a list of menu items that also
157	   allows per-item flags and a "selection" character to be specified.
158	   An array of menu_item */
159	MN_ITER_ITEMS   = 2,
160
161	/* A list of strings to be selected from - no associated actions.
162	   An array of const char * */
163	MN_ITER_STRINGS = 3
164} menu_iter_id;
165
166
167/* Class functions for menu row-level accessor functions */
168struct menu_iter
169{
170	/* Optional selection tag function */
171	char (*get_tag)(menu_type *menu, int oid);
172	/* Optional validity checker.  All rows are assumed valid if not present. */
173 	/* To support "hidden" items, it uses 3-level logic: 0 = no  1 = yes 2 = hide */
174	int (*valid_row)(menu_type *menu, int oid);
175	/* Displays a menu row at specified location */
176	display_row_f display_row;
177	/* Handler function called for selection or command key events */
178	bool (*row_handler)(char cmd, void *db, int oid);
179};
180
181
182/* A menu defines either an action
183 * or db row event
184 */
185struct menu_type
186{
187	/* menu inherits from panel */
188	event_listener target;
189	void (*refresh)();
190	region boundary;
191
192	/* set of commands that may be performed on a menu item */
193	const char *cmd_keys;
194
195	/* Public variables */
196	const char *title;
197	const char *prompt;
198
199	/* Keyboard shortcuts for menu selection */
200	/* IMPORTANT: this cannot intersect with cmd_keys */
201	const char *selections; 
202
203	int flags;              /* Flags specifying the behavior of this menu. */
204	int filter_count;       /* number of rows in current view */
205	const int *filter_list;       /* optional filter (view) of menu objects */
206
207	int count;              /* number of rows in underlying data set */
208	void *menu_data;  /* the data used to access rows. */
209
210  	/* auxiliary browser help function */
211	void (*browse_hook)(int oid, void *db, const region *loc);
212
213	/* These are "protected" - not visible for canned menu classes, */
214	/* The per-row functions  */
215	const menu_iter *row_funcs;
216
217
218	/* State variables for the menu */
219	int cursor;             /* Currently selected row */
220	int top;                /* Position in list for partial display */
221	region active;          /* Subregion actually active for selection */
222
223	/* helper functions for layout information. */
224	const menu_skin *skin;  /* Defines menu appearance */
225};
226
227
228/* 
229 * Select a row from a menu.
230 * 
231 * Arguments:
232 *  object_list - optional ordered subset of menu OID.  If NULL, cursor is used for OID
233 *  cursor - current (absolute) position in menu.  Modified on selection.
234 *  loc - location to display the menu.
235 * Return: A command key; cursor is set to the corresponding row.
236 * (This is a stand-in for a menu event)
237 * reserved commands are 0xff for selection and ESCAPE for escape.
238 */
239ui_event_data menu_select(menu_type *menu, int *cursor, int no_handle);
240
241/* TODO: This belongs in the VTAB */
242bool menu_layout(menu_type *menu, const region *loc);
243
244/* accessor & utility functions */
245void menu_set_filter(menu_type *menu, const int object_list[], int n);
246void menu_release_filter(menu_type *menu);
247
248
249/* Find a menu iterator struct */
250const menu_iter *find_menu_iter(menu_iter_id iter_id);
251
252/* Initialize a menu given skin ID and an iterator */
253bool menu_init(menu_type *menu, skin_id skin, const menu_iter *iter, const region *loc);
254
255/* Refresh the menu */
256void menu_refresh(menu_type *menu);
257
258
259#endif /* INCLUDED_UI_MENU_H */
260