/src/ui-menu.h
C Header | 260 lines | 100 code | 59 blank | 101 comment | 0 complexity | 10851f5edc89f2bad1bad747768f11e7 MD5 | raw file
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