chiark - git - mdw - ssr/blob - StraySrc/Libraries/Steel/h/menu

   1 /*
   2  * menu
   3  *
   4  *  A working menu system
   5  *
   6  * © 1992-1998 Straylight
   7  */
   8
   9 /*----- Licensing note ----------------------------------------------------*
  10  *
  11  * This file is part of Straylight's Steel library.
  12  *
  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)
  16  * any later version.
  17  *
  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.
  22  *
  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.
  26  */
  27
  28 #ifndef __menu_h
  29 #define __menu_h
  30
  31 #ifndef __wimp_h
  32 #include "wimp.h"
  33 #endif
  34
  35 #ifndef __event_h
  36 typedef struct menu__menustr *menu;
  37 typedef menu (*event_menu_maker)(void *handle);
  38 typedef void (*event_menu_proc)(void *handle, char* hit);
  39 #include "event.h"
  40 #endif
  41
  42 typedef void (*menu_selectProc)(int hits[],void *handle);
  43 typedef void (*menu_helpProc)(int hits[],void *handle);
  44
  45 /*---------------------------------------------------------------------------
  46
  47   The syntax of menu strings is an extension of the system used by the
  48   RISC_OSlib menu segment:
  49
  50     menu_description ::= <flags> <item> <sep> { <flags> <item> <sep> }
  51     flags ::= '!' | '~' | '>' | ' ' | '+'
  52     sep ::= ',' | '|'
  53     item ::= <a bunch of other characters>
  54
  55   flags have meanings as follows:
  56
  57     ' ' has no effect
  58     '~' shades the item
  59     '>' item has a menu dbox attached
  60     '!' item is ticked
  61     '+' open submenu even if item is shaded
  62
  63 ---------------------------------------------------------------------------*/
  64
  65 /*
  66  * menu menu_new(char *title,char *items)
  67  *
  68  * Use
  69  *  Creates a menu as per the old RISC_OSlib system.
  70  *
  71  * Parameters
  72  *  char *title == the menu title (truncated to 12 chars if necessary)
  73  *  char *items == the menu item text.  Data is indirected where required.
  74  *
  75  * Returns
  76  *  A pointer to the menu if successful, or a NULL pointer if not.
  77  */
  78
  79 menu menu_new(char *title,char *items);
  80
  81 /*
  82  * void menu_submenu(menu main,int item,menu submenu)
  83  *
  84  * Use
  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!
  87  *
  88  * Parameters
  89  *  menu main == the main menu
  90  *  int item == the menu item number
  91  *  menu submenu == the submenu
  92  */
  93
  94 void menu_submenu(menu main,int item,menu submenu);
  95
  96 /*
  97  * void menu_dispose(menu *m,BOOL recurse)
  98  *
  99  * Use
 100  *  Kill off a menu or menu tree.  Won't work on submenus.
 101  *
 102  * Parameters
 103  *  menu *m == pointer to menu to Domestos-ise.
 104  *  BOOL recurse == do we want to kill its submenus too?
 105  */
 106
 107 void menu_dispose(menu *m,BOOL recurse);
 108
 109 /*
 110  * wimp_menustr *menu_syshandle(menu m)
 111  *
 112  * Use
 113  *  Returns pointer to actual menu structure.
 114  *
 115  * Parameters
 116  *  menu m == menu handle for which structure is required.
 117  *
 118  * Returns
 119  *  A pointer to the WIMP menu structure.
 120  */
 121
 122 wimp_menustr *menu_syshandle(menu m);
 123
 124 /*
 125  * void menu_extend(menu m,char *items)
 126  *
 127  * Use
 128  *  Extend the given menu by a bit.
 129  *
 130  * Parameters
 131  *  menu m == the menu to extend
 132  *  char *items == the items to tag on the end
 133  */
 134
 135 void menu_extend(menu m,char *items);
 136
 137 /*
 138  * void menu_setflags(menu m,int i,BOOL tick,BOOL shade)
 139  *
 140  * Use
 141  *  Changes menu item properties.
 142  *
 143  * Parameters
 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
 148  */
 149
 150 void menu_setflags(menu m,int i,BOOL tick,BOOL shade);
 151
 152 /*
 153  * void menu_make_writeable(menu m,int i,char *buff,int bufflen,char *valid)
 154  *
 155  * Use
 156  *  Makes a menu entry writable (sorry about the spelling - it's Acorn's
 157  *  fault).
 158  *
 159  * Parameters
 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)
 165  */
 166
 167 void menu_make_writeable(menu m,int i,char *buff,int bufflen,char *valid);
 168
 169 /*
 170  * void menu_make_sprite(menu m,int i,char *name)
 171  *
 172  * Use
 173  *  Turns a menu entry into a sprite.  Utterly useless, but there you go...
 174  *
 175  * Parameters
 176  *  menu m == the menu we're dealing with
 177  *  int i == the item to sprite-ise
 178  *  char *name == the sprite name
 179  */
 180
 181 void menu_make_sprite(menu m,int i,char *name);
 182
 183 /*
 184  * void menu_redirectItem(menu m,int i,char *buff,int bufflen,char *valid)
 185  *
 186  * Use
 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
 189  *  important.
 190  *
 191  * Parameters
 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)
 197  */
 198
 199 void menu_redirectItem(menu m,int i,char *buff,int bufflen,char *valid);
 200
 201 /*
 202  * void menu_minWidth(menu m,int min)
 203  *
 204  * Use
 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.
 208  *
 209  * Parameters
 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.
 213  */
 214
 215 void menu_minWidth(menu m,int min);
 216
 217 /*
 218  * void menu_settitle(menu m,char *title)
 219  *
 220  * Use
 221  *  Change a menu title.
 222  *
 223  * Parameters
 224  *  menu m == the menu to change
 225  *  char *title == the new title
 226  */
 227
 228 void menu_settitle(menu m,char *title);
 229
 230 /*
 231  * void menu_attach
 232  * (
 233  *   wimp_w w,
 234  *   menu m,
 235  *   menu_selectProc sel,
 236  *   menu_helpProc help,
 237  *   void *handle
 238  * )
 239  *
 240  * Use
 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.
 246  *
 247  * Parameters
 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
 252  */
 253
 254 void menu_attach
 255 (
 256   wimp_w w,
 257   menu m,
 258   menu_selectProc sel,
 259   menu_helpProc help,
 260   void *handle
 261 );
 262
 263 /*
 264  * void menu_attachMaker
 265  * (
 266  *   wimp_w w,
 267  *   event_menu_maker m,
 268  *   menu_selectProc sel,
 269  *   menu_helpProc help,
 270  *   void *handle
 271  * )
 272  *
 273  * Use
 274  *  This routine deals with event_attachmenumaker as menu_attach deals with
 275  *  event_attachmenu.
 276  *
 277  * Parameters
 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
 282  */
 283
 284 void menu_attachMaker
 285 (
 286   wimp_w w,
 287   event_menu_maker m,
 288   menu_selectProc sel,
 289   menu_helpProc help,
 290   void *handle
 291 );
 292
 293 /*
 294  * void menu_open(menu m,menu_selectProc sel,menu_helpProc help,void *handle)
 295  *
 296  * Use
 297  *  Analagous to event_openMenu().
 298  *
 299  * Parameters
 300  *  As above.
 301  */
 302
 303 void menu_open(menu m,menu_selectProc sel,menu_helpProc help,void *handle);
 304
 305 /*
 306  * void menu_make(event_menu_maker m,menu_selectProc sel,menu_helpProc help,void *handle)
 307  *
 308  * Use
 309  *  Analagous to event_makeMenu().
 310  *
 311  * Parameters
 312  *  As above.
 313  */
 314
 315 void menu_make(event_menu_maker m,menu_selectProc sel,menu_helpProc help,void *handle);
 316
 317 /*
 318  * void menu_saveHandler(wimp_w w,menu_handler *h)
 319  *
 320  * Use
 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.
 326  *
 327  * Parameters
 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.
 330  */
 331
 332 typedef struct menu_handler
 333 {
 334   BOOL doneByMenu;
 335   union
 336   {
 337     struct
 338     {
 339       menu m;
 340       event_menu_maker make;
 341       menu_selectProc sel;
 342       menu_helpProc help;
 343       void *handle;
 344     }
 345     m;
 346     struct
 347     {
 348       menu m;
 349       event_menu_maker make;
 350       event_menu_proc proc;
 351       void *handle;
 352     }
 353     e;
 354   }
 355   info;
 356 }
 357 menu_handler;
 358
 359 void menu_saveHandler(wimp_w w,menu_handler *h);
 360
 361 /*
 362  * void menu_restoreHandler(wimp_w w,menu_handler *h)
 363  *
 364  * Use
 365  *  Restores handlers from a structure filled in by menu_saveHandler.
 366  *
 367  * Parameters
 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.
 370  */
 371
 372 void menu_restoreHandler(wimp_w w,menu_handler *h);
 373
 374 #endif