Angband
ui-menu.h
Go to the documentation of this file.
1 
20 #ifndef INCLUDED_UI_MENU_H
21 #define INCLUDED_UI_MENU_H
22 
23 #include "ui-output.h"
24 
25 /*** Constants ***/
26 
27 /* Colors for interactive menus */
28 enum
29 {
30  CURS_UNKNOWN = 0, /* Use gray / dark blue for cursor */
31  CURS_KNOWN = 1 /* Use white / light blue for cursor */
32 };
33 
37 typedef enum _menu_row_style_t {
41 
45 typedef enum _menu_row_validity_t {
50 
51 /* Cursor colours for different states */
52 extern const byte curs_attrs[2][2];
53 
54 /* Standard menu orderings */
55 extern const char lower_case[]; /* abc..z */
56 extern const char upper_case[]; /* ABC..Z */
57 extern const char all_letters[]; /* abc..zABC..Z */
58 
59 
60 /*
61  Together, these classes define the constant properties of
62  the various menu classes.
63 
64  A menu consists of:
65  - menu_iter, which describes how to handle the type of "list" that's
66  being displayed as a menu
67  - a menu_skin, which describes the layout of the menu on the screen.
68  - various bits and bobs of other data (e.g. the actual list of entries)
69  */
70 struct menu;
71 
72 
73 
74 /*** Predefined menu "skins" ***/
75 
79 typedef enum
80 {
81  /*
82  * A simple list of actions with an associated name and id.
83  * Private data: an array of menu_action
84  */
86 
87  /*
88  * A list of strings to be selected from - no associated actions.
89  * Private data: an array of const char *
90  */
92 } menu_iter_id;
93 
94 
98 typedef struct
99 {
100  int flags;
101  char tag;
102  const char *name;
103  void (*action)(const char *title, int row);
104 } menu_action;
105 
106 
110 #define MN_ACT_GRAYED 0x0001 /* Allows selection but no action */
111 #define MN_ACT_HIDDEN 0x0002 /* Row is hidden, but may be selected via tag */
112 
113 
117 typedef struct
118 {
119  /* Returns menu item tag (optional) */
120  char (*get_tag)(struct menu *menu, int oid);
121 
122  /*
123  * Validity checker (optional--all rows are assumed valid if not present)
124  * Return values will be interpreted as: 0 = no, 1 = yes, 2 = hide.
125  */
126  int (*valid_row)(struct menu *menu, int oid);
127 
128  /* Displays a menu row */
129  void (*display_row)(struct menu *menu, int oid, bool cursor,
130  int row, int col, int width);
131 
132  /* Handle 'positive' events (selections or cmd_keys) */
133  /* XXX split out into a select handler and a cmd_key handler */
134  bool (*row_handler)(struct menu *menu, const ui_event *event, int oid);
135 
136  /* Called when the screen resizes */
137  void (*resize)(struct menu *m);
138 } menu_iter;
139 
140 
141 
142 /*** Menu skins ***/
143 
147 typedef enum
148 {
151 } skin_id;
152 
153 
154 /* Class functions for menu layout */
155 typedef struct
156 {
157  /* Determines the cursor index given a (mouse) location */
158  int (*get_cursor)(int row, int col, int n, int top, region *loc);
159 
160  /* Displays the current list of visible menu items */
161  void (*display_list)(struct menu *menu, int cursor, int *top, region *);
162 
163  /* Specifies the relative menu item given the state of the menu */
164  char (*get_tag)(struct menu *menu, int pos);
165 
166  /* Process a direction */
167  ui_event (*process_dir)(struct menu *menu, int dir);
168 } menu_skin;
169 
170 
171 
172 /*** Base menu structure ***/
173 
177 enum
178 {
179  /* Tags are associated with the view, not the element */
180  MN_REL_TAGS = 0x01,
181 
182  /* No tags -- movement key and mouse browsing only */
183  MN_NO_TAGS = 0x02,
184 
185  /* Tags to be generated by the display function */
186  MN_PVT_TAGS = 0x04,
187 
188  /* Tag selections can be made regardless of the case of the key pressed.
189  * i.e. 'a' activates the line tagged 'A'. */
191 
192  /* double tap (or keypress) for selection; single tap is cursor movement */
193  MN_DBL_TAP = 0x10,
194 
195  /* no select events to be triggered */
197 };
198 
199 
200 /* Base menu type */
201 struct menu
202 {
204  const char *header;
205  const char *title;
206  const char *prompt;
207 
208  /* Keyboard shortcuts for menu selection-- shouldn't overlap cmd_keys */
209  const char *selections;
210 
211  /* String of characters that when pressed, menu handler should be called */
212  /* Mustn't overlap with 'selections' or some items may be unselectable */
213  const char *cmd_keys;
214 
215  /* auxiliary browser help function */
216  void (*browse_hook)(int oid, void *db, const region *loc);
217 
218  /* Flags specifying the behavior of this menu (from struct menu_flags) */
219  int flags;
220 
221 
224  /* Stored boundary, set by menu_layout(). This is used to calculate
225  * where the menu should be displayed on display & resize */
227 
228  int filter_count; /* number of rows in current view */
229  const int *filter_list; /* optional filter (view) of menu objects */
230 
231  int count; /* number of rows in underlying data set */
232  void *menu_data; /* the data used to access rows. */
233 
234  const menu_skin *skin; /* menu display style functions */
235  const menu_iter *row_funcs; /* menu skin functions */
236 
237  /* State variables */
238  int cursor; /* Currently selected row */
239  int top; /* Position in list for partial display */
240  region active; /* Subregion actually active for selection */
241  int cursor_x_offset; /* Adjustment to the default position of the cursor on a line. */
242 };
243 
244 
245 
246 /*** Menu API ***/
247 
251 struct menu *menu_new(skin_id, const menu_iter *iter);
252 struct menu *menu_new_action(menu_action *acts, size_t n);
253 
254 
258 void menu_init(struct menu *menu, skin_id skin, const menu_iter *iter);
259 
260 
264 const menu_iter *menu_find_iter(menu_iter_id iter_id);
265 
266 
273 void menu_setpriv(struct menu *menu, int count, void *data);
274 
275 
279 void *menu_priv(struct menu *menu);
280 
281 
282 /*
283  * Set a filter on what items a menu can display.
284  *
285  * Use this if your menu private data has 100 items, but you want to choose
286  * which ones of those to display at any given time, e.g. in an inventory menu.
287  * object_list[] should be an array of indexes to display, and n should be its
288  * length.
289  */
290 void menu_set_filter(struct menu *menu, const int object_list[], int n);
291 
292 
296 void menu_release_filter(struct menu *menu);
297 
298 
304 bool menu_layout(struct menu *menu, const region *loc);
305 
306 
312 void menu_refresh(struct menu *menu, bool reset_screen);
313 
314 
340 ui_event menu_select(struct menu *menu, int notify, bool popup);
341 
345 void menu_ensure_cursor_valid(struct menu *m);
346 
347 
348 /* Interal menu stuff that cmd-know needs because it's quite horrible */
349 bool menu_handle_mouse(struct menu *menu, const ui_event *in, ui_event *out);
350 bool menu_handle_keypress(struct menu *menu, const ui_event *in, ui_event *out);
351 
355 void menu_set_cursor_x_offset(struct menu *m, int offset);
356 
357 /*** Dynamic menu handling ***/
358 
359 struct menu *menu_dynamic_new(void);
360 void menu_dynamic_add(struct menu *m, const char *text, int value);
361 void menu_dynamic_add_valid(struct menu *m, const char *text, int value, menu_row_validity_t valid);
362 void menu_dynamic_add_label(struct menu *m, const char *text, const char label, int value, char *label_list);
363 void menu_dynamic_add_label_valid(struct menu *m, const char *text, const char label, int value, char *label_list, menu_row_validity_t valid);
364 size_t menu_dynamic_longest_entry(struct menu *m);
365 void menu_dynamic_calc_location(struct menu *m, int mx, int my);
366 int menu_dynamic_select(struct menu *m);
367 void menu_dynamic_free(struct menu *m);
368 
369 #endif /* INCLUDED_UI_MENU_H */