Initial revision

[ssr] / StraySrc / Libraries / Steel / h / menu

/*
 * menu
 *
 *  A working menu system
 *
 * © 1992-1998 Straylight
 */

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * Steel is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __menu_h
#define __menu_h

#ifndef __wimp_h
#include "wimp.h"
#endif

#ifndef __event_h
typedef struct menu__menustr *menu;
typedef menu (*event_menu_maker)(void *handle);
typedef void (*event_menu_proc)(void *handle, char* hit);
#include "event.h"
#endif

typedef void (*menu_selectProc)(int hits[],void *handle);
typedef void (*menu_helpProc)(int hits[],void *handle);

/*---------------------------------------------------------------------------

  The syntax of menu strings is an extension of the system used by the
  RISC_OSlib menu segment:

    menu_description ::= <flags> <item> <sep> { <flags> <item> <sep> }
    flags ::= '!' | '~' | '>' | ' ' | '+'
    sep ::= ',' | '|'
    item ::= <a bunch of other characters>

  flags have meanings as follows:

    ' ' has no effect
    '~' shades the item
    '>' item has a menu dbox attached
    '!' item is ticked
    '+' open submenu even if item is shaded

---------------------------------------------------------------------------*/

/*
 * menu menu_new(char *title,char *items)
 *
 * Use
 *  Creates a menu as per the old RISC_OSlib system.
 *
 * Parameters
 *  char *title == the menu title (truncated to 12 chars if necessary)
 *  char *items == the menu item text.  Data is indirected where required.
 *
 * Returns
 *  A pointer to the menu if successful, or a NULL pointer if not.
 */

menu menu_new(char *title,char *items);

/*
 * void menu_submenu(menu main,int item,menu submenu)
 *
 * Use
 *  Attaches a menu as a submenu, but it will put in a submenu warning flag,
 *  so the user-friendly too-many-windows messages come up right!
 *
 * Parameters
 *  menu main == the main menu
 *  int item == the menu item number
 *  menu submenu == the submenu
 */

void menu_submenu(menu main,int item,menu submenu);

/*
 * void menu_dispose(menu *m,BOOL recurse)
 *
 * Use
 *  Kill off a menu or menu tree.  Won't work on submenus.
 *
 * Parameters
 *  menu *m == pointer to menu to Domestos-ise.
 *  BOOL recurse == do we want to kill its submenus too?
 */

void menu_dispose(menu *m,BOOL recurse);

/*
 * wimp_menustr *menu_syshandle(menu m)
 *
 * Use
 *  Returns pointer to actual menu structure.
 *
 * Parameters
 *  menu m == menu handle for which structure is required.
 *
 * Returns
 *  A pointer to the WIMP menu structure.
 */

wimp_menustr *menu_syshandle(menu m);

/*
 * void menu_extend(menu m,char *items)
 *
 * Use
 *  Extend the given menu by a bit.
 *
 * Parameters
 *  menu m == the menu to extend
 *  char *items == the items to tag on the end
 */

void menu_extend(menu m,char *items);

/*
 * void menu_setflags(menu m,int i,BOOL tick,BOOL shade)
 *
 * Use
 *  Changes menu item properties.
 *
 * Parameters
 *  menu m == menu to change
 *  int i == menu item to change
 *  BOOL tick == tick the item
 *  BOOL shade == shade the item
 */

void menu_setflags(menu m,int i,BOOL tick,BOOL shade);

/*
 * void menu_make_writeable(menu m,int i,char *buff,int bufflen,char *valid)
 *
 * Use
 *  Makes a menu entry writable (sorry about the spelling - it's Acorn's
 *  fault).
 *
 * Parameters
 *  menu m == the menu in question
 *  int i == the item to be handled
 *  char *buff == where the data is to reside
 *  int bufflen == max length of data that can be crammed into buff
 *  char *valid == validation string (0 for none)
 */

void menu_make_writeable(menu m,int i,char *buff,int bufflen,char *valid);

/*
 * void menu_make_sprite(menu m,int i,char *name)
 *
 * Use
 *  Turns a menu entry into a sprite.  Utterly useless, but there you go...
 *
 * Parameters
 *  menu m == the menu we're dealing with
 *  int i == the item to sprite-ise
 *  char *name == the sprite name
 */

void menu_make_sprite(menu m,int i,char *name);

/*
 * void menu_redirectItem(menu m,int i,char *buff,int bufflen,char *valid)
 *
 * Use
 *  Allows you to make a menu item's data point to your workspace, so you
 *  can change the text of an item at any time.  The buffer length isn't
 *  important.
 *
 * Parameters
 *  menu m == the menu in question
 *  int i == the item to be handled
 *  char *buff == where the data is to reside
 *  int bufflen == max length of data that can be crammed into buff
 *  char *valid == validation string (0 for none)
 */

void menu_redirectItem(menu m,int i,char *buff,int bufflen,char *valid);

/*
 * void menu_minWidth(menu m,int min)
 *
 * Use
 *  Sets the minimum permissable width of a menu (in characters).  Note that
 *  this call will not make the menu thinner than the width calculated
 *  during menu_new or menu_extend.
 *
 * Parameters
 *  menu m == the menu to change
 *  int min == the minumum allowable width fro the menu in characters.  If
 *    0 is passed, the width reverts to the calculated width.
 */

void menu_minWidth(menu m,int min);

/*
 * void menu_settitle(menu m,char *title)
 *
 * Use
 *  Change a menu title.
 *
 * Parameters
 *  menu m == the menu to change
 *  char *title == the new title
 */

void menu_settitle(menu m,char *title);

/*
 * void menu_attach
 * (
 *   wimp_w w,
 *   menu m,
 *   menu_selectProc sel,
 *   menu_helpProc help,
 *   void *handle
 * )
 *
 * Use
 *  Basically equivalent to event_attachmenu, only it handles help requests
 *  neatly etc.  Source code compatibility *cannot* be assured, because I
 *  want to be able to expand this routine to cater for later changes.  I
 *  will try to soften the blow (if any) by supplying macros that will work
 *  with older programs, but I can't guarantee anything.
 *
 * Parameters
 *  wimp_w w == the window to attach to
 *  menu m == the menu to attach
 *  menu_selectProc sel == procedure to handle most selection-type events
 *  menu_helpProc help == procedure to handle help requests for the menu
 */

void menu_attach
(
  wimp_w w,
  menu m,
  menu_selectProc sel,
  menu_helpProc help,
  void *handle
);

/*
 * void menu_attachMaker
 * (
 *   wimp_w w,
 *   event_menu_maker m,
 *   menu_selectProc sel,
 *   menu_helpProc help,
 *   void *handle
 * )
 *
 * Use
 *  This routine deals with event_attachmenumaker as menu_attach deals with
 *  event_attachmenu.
 *
 * Parameters
 *  wimp_w w == the window to attach to
 *  menu m == the menu to attach
 *  menu_selectProc sel == procedure to handle most selection-type events
 *  menu_helpProc help == procedure to handle help requests for the menu
 */

void menu_attachMaker
(
  wimp_w w,
  event_menu_maker m,
  menu_selectProc sel,
  menu_helpProc help,
  void *handle
);

/*
 * void menu_open(menu m,menu_selectProc sel,menu_helpProc help,void *handle)
 *
 * Use
 *  Analagous to event_openMenu().
 *
 * Parameters
 *  As above.
 */

void menu_open(menu m,menu_selectProc sel,menu_helpProc help,void *handle);

/*
 * void menu_make(event_menu_maker m,menu_selectProc sel,menu_helpProc help,void *handle)
 *
 * Use
 *  Analagous to event_makeMenu().
 *
 * Parameters
 *  As above.
 */

void menu_make(event_menu_maker m,menu_selectProc sel,menu_helpProc help,void *handle);

/*
 * void menu_saveHandler(wimp_w w,menu_handler *h)
 *
 * Use
 *  Saves information about the menu handle for the given window in the
 *  block specified.  This can be used *only* to restore the handler for a
 *  window later (although it needn't be the same one).  Note too that the
 *  window need not have to have menu handlers registered using the menu
 *  calls, or even have any at all.
 *
 * Parameters
 *  wimp_w w == the window whose menu handlers we are to save
 *  menu_handler *h == pointer to a chunk of memory to fill in.
 */

typedef struct menu_handler
{
  BOOL doneByMenu;
  union
  {
    struct
    {
      menu m;
      event_menu_maker make;
      menu_selectProc sel;
      menu_helpProc help;
      void *handle;
    }
    m;
    struct
    {
      menu m;
      event_menu_maker make;
      event_menu_proc proc;
      void *handle;
    }
    e;
  }
  info;
}
menu_handler;

void menu_saveHandler(wimp_w w,menu_handler *h);

/*
 * void menu_restoreHandler(wimp_w w,menu_handler *h)
 *
 * Use
 *  Restores handlers from a structure filled in by menu_saveHandler.
 *
 * Parameters
 *  wimp_w w == the window whose handlers we are to set up.
 *  menu_handler *h == pointer to a chunk of memory filled in correctly.
 */

void menu_restoreHandler(wimp_w w,menu_handler *h);

#endif