home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / gcc / !GCC / patches / DeskLib / h / Menu < prev    next >
Encoding:
Text File  |  1994-10-03  |  7.0 KB  |  205 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Menu.h
  12.     Author:  Copyright © 1993 Jason Williams
  13.              Thanks to Shaun Blackmore, Tim Browse, and others for various
  14.              bits and pieces, menu template ideas, etc, which were mostly
  15.              not used for this simple implementation, but may be used in
  16.              the future.
  17.     Version: 1.00 (30 Apr 1993)
  18.     Purpose: Equivalent of RISC OS Lib's "menus" functions - Give a simple
  19.              method for creating and showing menus.
  20.  
  21.     Notes:   These are simple menu create and show functions along very
  22.              similar lines to RISC OS Lib's 'menu' functions. However, there
  23.              are major differences -
  24.                + menu items are ALWAYS indexed starting from 0.
  25.                + menu pointers point to real Wimp menu structures, no
  26.                  messing about
  27.                + Menu_Show is provided to show the menus for you, including
  28.                  placing a menu in the correct position over the icon bar.
  29. */
  30.  
  31.  
  32. #ifndef __dl_menu_h
  33. #define __dl_menu_h
  34.  
  35. #ifndef __dl_core_h
  36. #include "Core.h"
  37. #endif
  38.  
  39. #ifndef __dl_wimp_h
  40. #include "Wimp.h"
  41. #endif
  42.  
  43. #ifndef __dl_event_h
  44. #include "Event.h"
  45. #endif
  46.  
  47. #ifdef __cplusplus
  48. extern "C" {
  49. #endif
  50.  
  51.   /*  Menu_New()
  52.    *  Creates a new menu. "title" should be no more than 12 characters long
  53.    *  (including the terminator). "description" is a RISC OS Lib style
  54.    *  menu_new() string (Desktop C manual, page 240, but note their syntax
  55.    *  AND their example are both WRONG!), i.e.
  56.    *      opt   :- " "  no special options (i.e. leading spaces are skipped)
  57.    *               "!"  ticked
  58.    *               "~"  shaded
  59.    *               ">"  has submenu/subwindow
  60.    *               "-"  dotted
  61.    *      name  :- any character except "," and "|"
  62.    *      entry :- {opt}* name
  63.    *      sep   :- ","  to separate normal items
  64.    *               "|"  to separate items and place a dotted line between them
  65.    *      descr :- entry {sep entry}*
  66.    *
  67.    *      EXAMPLES:
  68.    *        "!Ticked,~Disabled,>Sub-menu,!~Ticked and disabled, Normal"
  69.    *        ">Info, Create| Quit"         ; info with sublink arrow
  70.    *                                      ; then create, dotted line, quit.
  71.    *
  72.    *  NOTES:
  73.    *    Menu_New needs Screen_() functions. It assumes you have called
  74.    *    Screen_CacheModeInfo() in this screen mode (to get screen_delta.x)
  75.    *    If this call fails (out of malloc memory) then it will call
  76.    *    Error_OutOfMemory() and then return NULL.
  77.    */
  78. extern menu_ptr Menu_New(char *title, char *description);
  79.  
  80.  
  81.   /*  Menu_Extend()
  82.    *  Extends (if possible) the menu by appending the items in "description"
  83.    *  onto the menu structure "menu". If the memory reallocation fails, it
  84.    *  returns the pointer to the old, UNCHANGED menu structure.
  85.    *  "description" is the same as for Menu_New().
  86.    */
  87. extern menu_ptr Menu_Extend(menu_ptr menu, char *description);
  88.  
  89.  
  90.   /*  Menu_Show()
  91.    *  Shows the given menu on screen, at the given x and y position.
  92.    *  Set (y = -1) to place the menu at the correct position above the
  93.    *  icon bar.
  94.    */
  95. extern void Menu_Show(menu_ptr menu, int x, int y);
  96.  
  97.  
  98.   /*  Menu_ShowLast()
  99.    *  Re-opens the last menu opened (call when a menu item is chosen using
  100.    *  the adjust mouse button to keep the menu open).
  101.    *  Note that if no menu has been opened, or if the last menu opened
  102.    *  has been "dispose"d, this will have bad (dire) results.
  103.    */
  104. extern void Menu_ShowLast(void);
  105.  
  106.  
  107.   /*  Menu_AddSubMenu()
  108.    *  Adds a menu to an existing menu as a submenu at a particular item.
  109.    */
  110. extern void Menu_AddSubMenu(menu_ptr menu, int entry, menu_ptr submenu);
  111.  
  112.  
  113.   /*  Menu_MakeWritable()
  114.    *  Makes a menu item writable. You supply the buffer into which the
  115.    *  menu item data will be written, as well as the size of this buffer
  116.    *  (including terminator), plus the validation string (as in Wimp icons)
  117.    */
  118. extern void Menu_MakeWritable(menu_ptr menu, int entry,
  119.                                char *buffer, int size, char *valid);
  120.  
  121.   /*  Menu_SetFlags()
  122.    *  Alters the state of a menu item. Setting ticked/shaded to 0 will
  123.    *  turn off the tick/make the item selectable. Setting them to 1 will
  124.    *  turn on a tick/make the item unselectable. Values other than 0 and 1
  125.    *  are undefined, so ensure the values you use are 0 and 1.
  126.    */
  127. extern void Menu_SetFlags(menu_ptr menu, int entry, int ticked, int shaded);
  128.  
  129.  
  130.   /*  Menu_GetFlags()
  131.    *  Reads the state of a menu item. If ticked/shaded are non-null
  132.    *  pointers then the ints will be updated to reflect the current
  133.    *  state of the menu entry.
  134.    */
  135. extern void Menu_GetFlags(menu_ptr menu, int entry, int *ticked, int *shaded);
  136.  
  137.  
  138.   /*  Menu_SetText()
  139.    *  Sets the text for a menu entry.
  140.    */
  141. extern void Menu_SetText(menu_ptr menu, int entry, char *text);
  142.  
  143.  
  144.   /*  Menu_GetText()
  145.    *  Finds the address of the text of a menu entry.
  146.    *  NOTE that this is the actual menu item text buffer, so treat it with
  147.    *  care!
  148.    */
  149. extern char *Menu_GetText(menu_ptr menu, int entry);
  150.  
  151.  
  152.   /*  Menu_CalcHeight()
  153.    *  Calculates the height of a menu in OS coords. For internal use.
  154.    */
  155. extern int Menu_CalcHeight(menu_ptr menu);
  156.  
  157.  
  158.   /*  Menu_SysHandle()
  159.    *  Returns a pointer to the 'underlying' Wimp menu definition. In DeskLib
  160.    *  this IS the menu definition.
  161.    */
  162. #define Menu_SysHandle(menu) (menu)
  163.  
  164.  
  165.   /*  Menu_SDispose()
  166.    *  Frees up the memory used by a menu. Note that this is a simple Dispose
  167.    *  which does not recursively dispose of attached submenus, and does not
  168.    *  dispose of memory used by long (indirected) item text.
  169.    */
  170. #define Menu_SDispose(menu) free(menu)
  171.  
  172.  
  173.   /*
  174.    *  Menu_RemoveItem()
  175.    *  Removes a menu item from a menu, shuffling items following it up the
  176.    *  menu. If there is only one item in the menu, nothing happens.
  177.    */
  178. extern void Menu_RemoveItem(menu_ptr menu, int entry);
  179.  
  180.  
  181.  
  182.   /*  Menu_Warn()
  183.    *  Sets up the given menu item as needing a message when the user follows
  184.    *  the submenu arrow. If yesno is TRUE, attaches the given handler to
  185.    *  menuwarnings, else releases the handler. Uses EventMsg.
  186.    */
  187. extern void Menu_Warn(menu_ptr menu, int entry, BOOL yesno,
  188.                       event_handler handler, void *reference);
  189.  
  190.  
  191.   /*  Global variables
  192.    *  menu_currentpos   holds the x,y position where the last menu was opened
  193.    *  menu_currentopen  is a pointer to the last menu opened.
  194.    *  If no menu has been opened, or the last menu has been disposed, then
  195.    *  these values will be invalid - use with care.
  196.    */
  197. extern wimp_point menu_currentpos;
  198. extern menu_ptr   menu_currentopen;
  199.  
  200. #ifdef __cplusplus
  201.            }
  202. #endif
  203.  
  204. #endif
  205.