4 * A working menu system
6 * © 1992-1998 Straylight
9 /*----- Licensing note ----------------------------------------------------*
11 * This file is part of Straylight's Steel library.
13 * Steel is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2, or (at your option)
18 * Steel is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
23 * You should have received a copy of the GNU General Public License
24 * along with Steel. If not, write to the Free Software Foundation,
25 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
36 typedef struct menu__menustr *menu;
37 typedef menu (*event_menu_maker)(void *handle);
38 typedef void (*event_menu_proc)(void *handle, char* hit);
42 typedef void (*menu_selectProc)(int hits[],void *handle);
43 typedef void (*menu_helpProc)(int hits[],void *handle);
45 /*---------------------------------------------------------------------------
47 The syntax of menu strings is an extension of the system used by the
48 RISC_OSlib menu segment:
50 menu_description ::= <flags> <item> <sep> { <flags> <item> <sep> }
51 flags ::= '!' | '~' | '>' | ' ' | '+'
53 item ::= <a bunch of other characters>
55 flags have meanings as follows:
59 '>' item has a menu dbox attached
61 '+' open submenu even if item is shaded
63 ---------------------------------------------------------------------------*/
66 * menu menu_new(char *title,char *items)
69 * Creates a menu as per the old RISC_OSlib system.
72 * char *title == the menu title (truncated to 12 chars if necessary)
73 * char *items == the menu item text. Data is indirected where required.
76 * A pointer to the menu if successful, or a NULL pointer if not.
79 menu menu_new(char *title,char *items);
82 * void menu_submenu(menu main,int item,menu submenu)
85 * Attaches a menu as a submenu, but it will put in a submenu warning flag,
86 * so the user-friendly too-many-windows messages come up right!
89 * menu main == the main menu
90 * int item == the menu item number
91 * menu submenu == the submenu
94 void menu_submenu(menu main,int item,menu submenu);
97 * void menu_dispose(menu *m,BOOL recurse)
100 * Kill off a menu or menu tree. Won't work on submenus.
103 * menu *m == pointer to menu to Domestos-ise.
104 * BOOL recurse == do we want to kill its submenus too?
107 void menu_dispose(menu *m,BOOL recurse);
110 * wimp_menustr *menu_syshandle(menu m)
113 * Returns pointer to actual menu structure.
116 * menu m == menu handle for which structure is required.
119 * A pointer to the WIMP menu structure.
122 wimp_menustr *menu_syshandle(menu m);
125 * void menu_extend(menu m,char *items)
128 * Extend the given menu by a bit.
131 * menu m == the menu to extend
132 * char *items == the items to tag on the end
135 void menu_extend(menu m,char *items);
138 * void menu_setflags(menu m,int i,BOOL tick,BOOL shade)
141 * Changes menu item properties.
144 * menu m == menu to change
145 * int i == menu item to change
146 * BOOL tick == tick the item
147 * BOOL shade == shade the item
150 void menu_setflags(menu m,int i,BOOL tick,BOOL shade);
153 * void menu_make_writeable(menu m,int i,char *buff,int bufflen,char *valid)
156 * Makes a menu entry writable (sorry about the spelling - it's Acorn's
160 * menu m == the menu in question
161 * int i == the item to be handled
162 * char *buff == where the data is to reside
163 * int bufflen == max length of data that can be crammed into buff
164 * char *valid == validation string (0 for none)
167 void menu_make_writeable(menu m,int i,char *buff,int bufflen,char *valid);
170 * void menu_make_sprite(menu m,int i,char *name)
173 * Turns a menu entry into a sprite. Utterly useless, but there you go...
176 * menu m == the menu we're dealing with
177 * int i == the item to sprite-ise
178 * char *name == the sprite name
181 void menu_make_sprite(menu m,int i,char *name);
184 * void menu_redirectItem(menu m,int i,char *buff,int bufflen,char *valid)
187 * Allows you to make a menu item's data point to your workspace, so you
188 * can change the text of an item at any time. The buffer length isn't
192 * menu m == the menu in question
193 * int i == the item to be handled
194 * char *buff == where the data is to reside
195 * int bufflen == max length of data that can be crammed into buff
196 * char *valid == validation string (0 for none)
199 void menu_redirectItem(menu m,int i,char *buff,int bufflen,char *valid);
202 * void menu_minWidth(menu m,int min)
205 * Sets the minimum permissable width of a menu (in characters). Note that
206 * this call will not make the menu thinner than the width calculated
207 * during menu_new or menu_extend.
210 * menu m == the menu to change
211 * int min == the minumum allowable width fro the menu in characters. If
212 * 0 is passed, the width reverts to the calculated width.
215 void menu_minWidth(menu m,int min);
218 * void menu_settitle(menu m,char *title)
221 * Change a menu title.
224 * menu m == the menu to change
225 * char *title == the new title
228 void menu_settitle(menu m,char *title);
235 * menu_selectProc sel,
236 * menu_helpProc help,
241 * Basically equivalent to event_attachmenu, only it handles help requests
242 * neatly etc. Source code compatibility *cannot* be assured, because I
243 * want to be able to expand this routine to cater for later changes. I
244 * will try to soften the blow (if any) by supplying macros that will work
245 * with older programs, but I can't guarantee anything.
248 * wimp_w w == the window to attach to
249 * menu m == the menu to attach
250 * menu_selectProc sel == procedure to handle most selection-type events
251 * menu_helpProc help == procedure to handle help requests for the menu
264 * void menu_attachMaker
267 * event_menu_maker m,
268 * menu_selectProc sel,
269 * menu_helpProc help,
274 * This routine deals with event_attachmenumaker as menu_attach deals with
278 * wimp_w w == the window to attach to
279 * menu m == the menu to attach
280 * menu_selectProc sel == procedure to handle most selection-type events
281 * menu_helpProc help == procedure to handle help requests for the menu
284 void menu_attachMaker
294 * void menu_open(menu m,menu_selectProc sel,menu_helpProc help,void *handle)
297 * Analagous to event_openMenu().
303 void menu_open(menu m,menu_selectProc sel,menu_helpProc help,void *handle);
306 * void menu_make(event_menu_maker m,menu_selectProc sel,menu_helpProc help,void *handle)
309 * Analagous to event_makeMenu().
315 void menu_make(event_menu_maker m,menu_selectProc sel,menu_helpProc help,void *handle);
318 * void menu_saveHandler(wimp_w w,menu_handler *h)
321 * Saves information about the menu handle for the given window in the
322 * block specified. This can be used *only* to restore the handler for a
323 * window later (although it needn't be the same one). Note too that the
324 * window need not have to have menu handlers registered using the menu
325 * calls, or even have any at all.
328 * wimp_w w == the window whose menu handlers we are to save
329 * menu_handler *h == pointer to a chunk of memory to fill in.
332 typedef struct menu_handler
340 event_menu_maker make;
349 event_menu_maker make;
350 event_menu_proc proc;
359 void menu_saveHandler(wimp_w w,menu_handler *h);
362 * void menu_restoreHandler(wimp_w w,menu_handler *h)
365 * Restores handlers from a structure filled in by menu_saveHandler.
368 * wimp_w w == the window whose handlers we are to set up.
369 * menu_handler *h == pointer to a chunk of memory filled in correctly.
372 void menu_restoreHandler(wimp_w w,menu_handler *h);