home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / desklib / !DeskLib / h / Menu < prev    next >
Encoding:
Text File  |  1994-05-22  |  7.0 KB  |  198 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.  
  48.   /*  Menu_New()
  49.    *  Creates a new menu. "title" should be no more than 12 characters long
  50.    *  (including the terminator). "description" is a RISC OS Lib style
  51.    *  menu_new() string (Desktop C manual, page 240, but note their syntax
  52.    *  AND their example are both WRONG!), i.e.
  53.    *      opt   :- " "  no special options (i.e. leading spaces are skipped)
  54.    *               "!"  ticked
  55.    *               "~"  shaded
  56.    *               ">"  has submenu/subwindow
  57.    *               "-"  dotted
  58.    *      name  :- any character except "," and "|"
  59.    *      entry :- {opt}* name
  60.    *      sep   :- ","  to separate normal items
  61.    *               "|"  to separate items and place a dotted line between them
  62.    *      descr :- entry {sep entry}*
  63.    *
  64.    *      EXAMPLES:
  65.    *        "!Ticked,~Disabled,>Sub-menu,!~Ticked and disabled, Normal"
  66.    *        ">Info, Create| Quit"         ; info with sublink arrow
  67.    *                                      ; then create, dotted line, quit.
  68.    *
  69.    *  NOTES:
  70.    *    Menu_New needs Screen_() functions. It assumes you have called
  71.    *    Screen_CacheModeInfo() in this screen mode (to get screen_delta.x)
  72.    *    If this call fails (out of malloc memory) then it will call
  73.    *    Error_OutOfMemory() and then return NULL.
  74.    */
  75. extern menu_ptr Menu_New(char *title, char *description);
  76.  
  77.  
  78.   /*  Menu_Extend()
  79.    *  Extends (if possible) the menu by appending the items in "description"
  80.    *  onto the menu structure "menu". If the memory reallocation fails, it
  81.    *  returns the pointer to the old, UNCHANGED menu structure.
  82.    *  "description" is the same as for Menu_New().
  83.    */
  84. extern menu_ptr Menu_Extend(menu_ptr menu, char *description);
  85.  
  86.  
  87.   /*  Menu_Show()
  88.    *  Shows the given menu on screen, at the given x and y position.
  89.    *  Set (y = -1) to place the menu at the correct position above the
  90.    *  icon bar.
  91.    */
  92. extern void Menu_Show(menu_ptr menu, int x, int y);
  93.  
  94.  
  95.   /*  Menu_ShowLast()
  96.    *  Re-opens the last menu opened (call when a menu item is chosen using
  97.    *  the adjust mouse button to keep the menu open).
  98.    *  Note that if no menu has been opened, or if the last menu opened
  99.    *  has been "dispose"d, this will have bad (dire) results.
  100.    */
  101. extern void Menu_ShowLast(void);
  102.  
  103.  
  104.   /*  Menu_AddSubMenu()
  105.    *  Adds a menu to an existing menu as a submenu at a particular item.
  106.    */
  107. extern void Menu_AddSubMenu(menu_ptr menu, int entry, menu_ptr submenu);
  108.  
  109.  
  110.   /*  Menu_MakeWritable()
  111.    *  Makes a menu item writable. You supply the buffer into which the
  112.    *  menu item data will be written, as well as the size of this buffer
  113.    *  (including terminator), plus the validation string (as in Wimp icons)
  114.    */
  115. extern void Menu_MakeWritable(menu_ptr menu, int entry,
  116.                                char *buffer, int size, char *valid);
  117.  
  118.   /*  Menu_SetFlags()
  119.    *  Alters the state of a menu item. Setting ticked/shaded to 0 will
  120.    *  turn off the tick/make the item selectable. Setting them to 1 will
  121.    *  turn on a tick/make the item unselectable. Values other than 0 and 1
  122.    *  are undefined, so ensure the values you use are 0 and 1.
  123.    */
  124. extern void Menu_SetFlags(menu_ptr menu, int entry, int ticked, int shaded);
  125.  
  126.  
  127.   /*  Menu_GetFlags()
  128.    *  Reads the state of a menu item. If ticked/shaded are non-null
  129.    *  pointers then the ints will be updated to reflect the current
  130.    *  state of the menu entry.
  131.    */
  132. extern void Menu_GetFlags(menu_ptr menu, int entry, int *ticked, int *shaded);
  133.  
  134.  
  135.   /*  Menu_SetText()
  136.    *  Sets the text for a menu entry.  
  137.    */
  138. extern void Menu_SetText(menu_ptr menu, int entry, char *text);
  139.  
  140.  
  141.   /*  Menu_GetText()
  142.    *  Finds the address of the text of a menu entry.
  143.    *  NOTE that this is the actual menu item text buffer, so treat it with
  144.    *  care!
  145.    */
  146. extern char *Menu_GetText(menu_ptr menu, int entry);
  147.  
  148.  
  149.   /*  Menu_CalcHeight()
  150.    *  Calculates the height of a menu in OS coords. For internal use.
  151.    */
  152. extern int Menu_CalcHeight(menu_ptr menu);
  153.  
  154.  
  155.   /*  Menu_SysHandle()
  156.    *  Returns a pointer to the 'underlying' Wimp menu definition. In DeskLib
  157.    *  this IS the menu definition.
  158.    */
  159. #define Menu_SysHandle(menu) (menu)
  160.  
  161.  
  162.   /*  Menu_SDispose()
  163.    *  Frees up the memory used by a menu. Note that this is a simple Dispose
  164.    *  which does not recursively dispose of attached submenus, and does not
  165.    *  dispose of memory used by long (indirected) item text.
  166.    */
  167. #define Menu_SDispose(menu) free(menu)
  168.  
  169.  
  170.   /*
  171.    *  Menu_RemoveItem()
  172.    *  Removes a menu item from a menu, shuffling items following it up the
  173.    *  menu. If there is only one item in the menu, nothing happens.
  174.    */
  175. extern void Menu_RemoveItem(menu_ptr menu, int entry);
  176.  
  177.  
  178.  
  179.   /*  Menu_Warn()
  180.    *  Sets up the given menu item as needing a message when the user follows
  181.    *  the submenu arrow. If yesno is TRUE, attaches the given handler to
  182.    *  menuwarnings, else releases the handler. Uses EventMsg.
  183.    */
  184. extern void Menu_Warn(menu_ptr menu, int entry, BOOL yesno,
  185.                       event_handler handler, void *reference);
  186.  
  187.  
  188.   /*  Global variables
  189.    *  menu_currentpos   holds the x,y position where the last menu was opened
  190.    *  menu_currentopen  is a pointer to the last menu opened.
  191.    *  If no menu has been opened, or the last menu has been disposed, then
  192.    *  these values will be invalid - use with care.
  193.    */
  194. extern wimp_point menu_currentpos;
  195. extern menu_ptr   menu_currentopen;
  196.  
  197. #endif
  198.