home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / Menu < prev    next >
Encoding:
Text File  |  1996-05-21  |  11.8 KB  |  347 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, 1994, 1995 Jason Williams, Julian Smith,
  13.                                           Brian Scattergood.
  14.              Thanks to Shaun Blackmore, Tim Browse, and others for various
  15.              bits and pieces, menu template ideas, etc, which were mostly
  16.              not used for this simple implementation, but may be used in
  17.              the future.
  18.     Version: 1.03 (Dec 1994)
  19.     Purpose: Equivalent of RISC OS Lib's "menus" functions - Give a simple
  20.              method for creating and showing menus.
  21.     History: 1.03 (Dec 1994)
  22.              1.04 (05 Oct 1995) JS    Added Desk_Menu_AddSubWindow.
  23.              1.05 (31 Oct 1995) JS, BS Added Desk_Menu_SetNotify macro.
  24.              
  25.     Notes:   These are simple menu create and show functions along very
  26.              similar lines to RISC OS Lib's 'menu' functions. However, there
  27.              are major differences -
  28.                + menu items are ALWAYS indexed starting from 0.
  29.                + menu pointers point to real Wimp menu structures, no
  30.                  messing about
  31.                + Desk_Menu_Show is provided to show the menus for you, including
  32.                  placing a menu in the correct position over the icon bar.
  33. */
  34.  
  35.  
  36. #ifndef __Desk_Menu_h
  37. #define __Desk_Menu_h
  38.  
  39. #ifdef __cplusplus
  40.     extern "C" {
  41. #endif
  42.  
  43.  
  44. #ifndef __Desk_Core_h
  45. #include "Desk.Core.h"
  46. #endif
  47.  
  48. #ifndef __Desk_Wimp_h
  49. #include "Desk.Wimp.h"
  50. #endif
  51.  
  52. #ifndef __Desk_Event_h
  53. #include "Desk.Event.h"
  54. #endif
  55.  
  56.  
  57. extern Desk_menu_ptr Desk_Menu_New( const char *title, const char *description);
  58.   /*
  59.    *  Creates a new menu. "title" should be no more than 12 characters long
  60.    *  (including the terminator). "description" is a RISC OS Lib style
  61.    *  Desk_menu_new() string (Desktop C manual, page 240, but note their syntax
  62.    *  AND their example are both WRONG!), i.e.
  63.    *      opt   :- " "  no special options (i.e. leading spaces are skipped)
  64.    *               "!"  ticked
  65.    *               "~"  shaded
  66.    *               ">"  has submenu/subwindow
  67.    *               "-"  dotted
  68.    *      name  :- any character except ", " and "|"
  69.    *      entry :- {opt}* name
  70.    *      sep   :- ", "  to separate normal items
  71.    *               "|"  to separate items and place a dotted line between them
  72.    *      descr :- entry {sep entry}*
  73.    *
  74.    *      EXAMPLES:
  75.    *        "!Ticked, ~Disabled, >Sub-menu, !~Ticked and disabled, Normal"
  76.    *        ">Info, Create| Quit"         ; info with sublink arrow
  77.    *                                      ; then create, dotted line, quit.
  78.    *
  79.    *  NOTES:
  80.    *    If this call fails (out of malloc memory) then it will call
  81.    *    Desk_Error_OutOfMemory() and then return NULL.
  82.    */
  83.  
  84.  
  85. extern Desk_menu_ptr Desk_Menu_Extend(Desk_menu_ptr menu, const char *description);
  86.   /*
  87.    *  Extends (if possible) the menu by appending the items in "description"
  88.    *  onto the menu structure "menu". If the memory reallocation fails, it
  89.    *  returns the pointer to the old, UNCHANGED menu structure.
  90.    *  "description" is the same as for Desk_Menu_New().
  91.    */
  92.  
  93.  
  94. extern void Desk_Menu_Show(Desk_menu_ptr menu, int x, int y);
  95.   /*
  96.    *  Shows the given menu on screen, at the given x and y position.
  97.    *  Set (y = -1) to place the menu at the correct position above the
  98.    *  icon bar.
  99.    */
  100.  
  101.  
  102. extern void Desk_Menu_ShowLast(void);
  103.   /*
  104.    *  Re-opens the last menu opened (call when a menu item is chosen using
  105.    *  the adjust mouse button to keep the menu open).
  106.    *  Note that if no menu has been opened, or if the last menu opened
  107.    *  has been "dispose"d, this will have bad (dire) results.
  108.    */
  109.  
  110.  
  111. extern void Desk_Menu_PopUp(Desk_menu_ptr menu, Desk_window_handle window, Desk_icon_handle icon);
  112.   /*
  113.    *  Shows a menu just beside the given icon, as in the Acorn style guide
  114.    *  for popups (who cares if it's a pain in the ass moving the pointer
  115.    *  all the way over there instead of having the menu pop up in a useful
  116.    *  place, right? ;-)
  117.    */
  118.  
  119. extern void Desk_Menu_PopUpAuto(Desk_menu_ptr menu);
  120.   /*  PopUpAuto is a variant which determines the icon to use from the
  121.    *  last Wimp event processed (uses Desk_Event_ stuff). Useful in a default
  122.    *  handler. If no icon info can be found from the last event, nothing
  123.    *  happens.
  124.    */
  125.  
  126.  
  127.  
  128. extern void Desk_Menu_AddSubMenu(Desk_menu_ptr menu, int entry, Desk_menu_ptr submenu);
  129.   /*
  130.    *  Adds a menu to an existing menu as a submenu at a particular item.
  131.    */
  132.  
  133. #define    Desk_Menu_AddSubWindow( menu, entry, window)    \
  134.         Desk_Menu_AddSubMenu( menu, entry, (Desk_menu_ptr) window)
  135. /*
  136. Use this to add a window (eg an info box) to a menu. 'window' should be
  137. the window-handle of the window.
  138.  */
  139.  
  140. extern void Desk_Menu_MakeIndirected(Desk_menu_ptr menu, int entry,
  141.                                 const char *buffer, int size);
  142.   /*
  143.    *  Converts a menu item into an indirected item, setting it to use the
  144.    *  given buffer (thus setting it to use different text)
  145.    *  SeeAlso: Desk_Menu_SetText; Desk_Menu_ReviseWidth
  146.    */
  147.  
  148. extern void Desk_Menu_MakeWritable(Desk_menu_ptr menu, int entry,
  149.                                const char *buffer, int size, const char *valid);
  150.   /*
  151.    *  Makes a menu item writable. You supply the buffer into which the
  152.    *  menu item data will be written, as well as the size of this buffer
  153.    *  (including terminator), plus the validation string (as in Wimp icons)
  154.    */
  155.  
  156. extern void Desk_Menu_SetFlags(Desk_menu_ptr menu, int entry, int ticked, int shaded);
  157.   /*
  158.    *  Alters the state of a menu item. Setting ticked/shaded to 0 will
  159.    *  turn off the tick/make the item selectable. Setting them to 1 will
  160.    *  turn on a tick/make the item unselectable. Values other than 0 and 1
  161.    *  are undefined, so ensure the values you use are 0 and 1.
  162.    */
  163.  
  164.  
  165. extern void Desk_Menu_GetFlags(Desk_menu_ptr menu, int entry, int *ticked, int *shaded);
  166.   /*
  167.    *  Reads the state of a menu item. If ticked/shaded are non-null
  168.    *  pointers then the ints will be updated to reflect the current
  169.    *  state of the menu entry.
  170.    */
  171.  
  172.  
  173. extern void Desk_Menu_SetText(Desk_menu_ptr menu, int entry, const char *text);
  174.   /*
  175.    *  Sets the text for a menu entry.  
  176.    *  SeeAlso: Desk_Menu_MakeIndirected; Desk_Menu_ReviseWidth
  177.    */
  178.  
  179.  
  180. extern char *Desk_Menu_GetText(Desk_menu_ptr menu, int entry);
  181.   /*
  182.    *  Finds the address of the text of a menu entry.
  183.    *  NOTE that this is the actual menu item text buffer, so treat it with
  184.    *  care!
  185.    */
  186.  
  187.  
  188. extern int Desk_Menu_CalcHeight(Desk_menu_ptr menu);
  189.   /*
  190.    *  Calculates the height of a menu in OS coords. For internal use.
  191.    */
  192.  
  193.  
  194. #define Desk_Menu_SysHandle(menu) (menu)
  195.   /*
  196.    *  Returns a pointer to the 'underlying' Wimp menu definition. In DeskLib
  197.    *  this IS the menu definition.
  198.    */
  199.  
  200.  
  201. #define Desk_Menu_SDispose(menu) free(menu)
  202.   /*
  203.    *  Frees up the memory used by a menu. Note that this is a simple Dispose
  204.    *  which does not recursively dispose of attached submenus, and does not
  205.    *  dispose of memory used by long (indirected) item text.
  206.    */
  207.  
  208.  
  209. extern void Desk_Menu_FullDispose(Desk_menu_ptr menu);
  210.   /*
  211.    *  Frees up the memory used by a menu. Note that this also
  212.    *  does not recursively dispose of attached submenus.
  213.    *  It does, however, dispose of all indirected menu data
  214.    */
  215.  
  216.  
  217. extern void Desk_Menu_RemoveItem(Desk_menu_ptr menu, int entry);
  218.   /*
  219.    *
  220.    *  Removes a menu item from a menu, shuffling items following it up the
  221.    *  menu. If there is only one item in the menu, nothing happens.
  222.    */
  223.  
  224.  
  225.  
  226. extern void Desk_Menu_Warn(Desk_menu_ptr menu, int entry, Desk_bool yesno,
  227.                       Desk_event_handler handler, void *reference);
  228.   /*
  229.    *  Sets up the given menu item as needing a message when the user follows
  230.    *  the submenu arrow. If yesno is Desk_bool_TRUE, attaches the given handler to
  231.    *  menuwarnings, else releases the handler. Uses EventMsg.
  232.    */
  233.  
  234.  
  235. extern void Desk_Menu_ReviseWidth(Desk_menu_ptr menu);
  236. /*
  237.  *  Revises a menu's width, by scanning through all the items.
  238.  *  The title width is also taken into consideration.
  239.  *  It is assumed that there is AT LEAST ONE item in the menu.
  240.  *
  241.  *  Use it after using Desk_Menu_SetText(), or when updating the
  242.  *  contents of an indirected text menu item, ie when having
  243.  *  used Desk_Menu_MakeIndirected().
  244.  */
  245.  
  246.  
  247. #define    Desk_Menu_FirstItem(menu) ((Desk_menu_item *) (((Desk_menu_ptr) (menu) + 1)))
  248. /*
  249. Very useful macro for messing around with Desk_menu_block's. Treat like:
  250.  
  251. Desk_menu_item *Desk_Menu_FirstItem( Desk_menu_ptr *menu);
  252.  
  253. You can do things like (for eg)
  254. 'Desk_Menu_FirstItem( menu)[5].menuflags.data.shaded = Desk_bool_TRUE;'
  255. - this will shade menu item number 5.
  256. */
  257.  
  258.  
  259.  
  260.  
  261. #define Desk_Menu_SetNotify( menu, entry, notify)    \
  262.     Desk_Menu_FirstItem(menu)[entry].menuflags.data.notifysub = (notify)
  263. /*
  264. Treat like:
  265.  
  266. void Desk_Menu_SetNotify( Desk_menu_ptr* menu, int entry, Desk_bool notify);
  267.  
  268. Alters the notify bit of a menu item. Setting notify to 0 will inhibit
  269. the generation of notification messages for that item (The default under
  270. DeskLib for submenu items is notification enabled). Values other than 0
  271. and 1 are undefined, so ensure the value you use is 0 or 1.
  272.  */
  273.  
  274.  
  275. #define Desk_Menu_FontMenu_NOTICK      0             /* don't tick anything */
  276. #define Desk_Menu_FontMenu_TICKSYSFONT ((char *)1)   /* tick the system font entry */
  277.  
  278. extern Desk_menu_ptr Desk_Menu_FontMenu(Desk_bool sysfont, const char *tick);
  279.   /*
  280.    *  Returns a pointer to a font menu, or 0 if it couldn't make one.
  281.    *  Set sysfont to Desk_bool_TRUE to add 'System font' at the top of the menu.
  282.    *  Set tick to a font name to tick it, or Desk_Menu_FontMenu_<x> for
  283.    *  something else.
  284.    *  Use Desk_Menu_FontMenu3 if you don't want the RISC OS 2 compatability
  285.    *  code dragged in. Under RISC OS 2, you get a plain list of fonts
  286.    *  without submenus. If the user has RISC OS 2, it's their own fault,
  287.    *  but at least it'll work.
  288.    */
  289.  
  290. extern Desk_menu_ptr Desk_Menu_FontMenu3(Desk_bool sysfont, const char *tick);
  291. /*
  292. RISC OS 3 version of Desk_Menu_FontMenu.
  293.  */
  294.  
  295. extern char *Desk_Menu_FontMenuDecode(const int *selection);
  296.   /* return pointers to font name given selection of entries within menu
  297.    * or 0 if an error occured 
  298.    * Use MenuFontMenuDecode3 to avoid RISCOS2 compatability code being included
  299.    */
  300.  
  301. extern char *Desk_Menu_FontMenuDecode3(const int *selection);
  302.  
  303.  
  304.  
  305.  
  306. #ifdef Desk__using_SDLS
  307.   extern Desk_menu_ptr   *Desk_Menu__Ref_fontmenu( void);
  308.   extern Desk_wimp_point *Desk_Menu__Ref_currentpos( void);
  309.   extern Desk_menu_ptr   *Desk_Menu__Ref_currentopen( void);
  310. #endif
  311.  
  312. #if defined( Desk__using_SDLS) && !defined( Desk__making_Menu)
  313.  
  314.   #define Desk_menu_fontmenu    (*Desk_Menu__Ref_fontmenu())
  315.   #define Desk_menu_currentpos  (*Desk_Menu__Ref_currentpos())
  316.   #define Desk_menu_currentopen (*Desk_Menu__Ref_currentopen())
  317.  
  318. #else
  319.  
  320.   extern Desk_menu_ptr   Desk_menu_fontmenu;
  321. /*
  322. only for comparison with Desk_menu_currentopen. This is defined in an
  323. assembler file, so won't work well in the dynamic-linking DeskLib.
  324. */
  325.  
  326.   extern Desk_wimp_point Desk_menu_currentpos; 
  327. /*
  328. holds the x, y position where the last menu was opened. If no menu has
  329. been opened, or the last menu has been disposed, then this values will
  330. be invalid - use with care.
  331. */
  332.  
  333.   extern Desk_menu_ptr   Desk_menu_currentopen; 
  334. /* pointer to the last menu opened. If no menu has been opened, or the
  335. last menu has been disposed, then this values will be invalid - use with
  336. care.
  337. */
  338. #endif
  339.  
  340.  
  341. #ifdef __cplusplus
  342. }
  343. #endif
  344.  
  345.  
  346. #endif
  347.