home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / clib / progs / timslib / TimsLib / h / Menu < prev    next >
Encoding:
Text File  |  1993-01-21  |  9.7 KB  |  253 lines
  1. /*
  2.    Menu.h - a replacement for RISC_OSLib's menu module.
  3.  
  4. */
  5. /*                           
  6.  
  7.   #####                 #         #
  8.     #    #              #      #  #
  9.     #                   #         #
  10.     #   ##  ####   #### #     ##  ####
  11.     #    #  # # # #     #      #  #   #
  12.     #    #  # # #  ###  #      #  #   #
  13.     #    #  # # #     # #      #  #   #
  14.     #   ### # # # ####  ##### ### ####
  15.  
  16. -----------------------------------------------------------------------------
  17.  
  18. This is source for use with the 'DeskLib' Wimp C programming library for
  19. Risc OS. I currently use v1.04 of DeskLib.  This source is FreeWare, which
  20. means you can use it to write commercial applications, but you may not charge
  21. *in any way* for the distribution of this source.  I (Tim Browse) retain
  22. all copyright on this source.
  23.  
  24. This source is provided 'as is' and I offer no guarantees that is useful,
  25. bug-free, commented, that it will compile, or even that it exists.
  26.  
  27. If it breaks in half, you own both pieces.
  28.  
  29. All source © Tim Browse 1993
  30.  
  31. -----------------------------------------------------------------------------
  32.  
  33. */
  34.  
  35. #ifndef __timslib__menu_h
  36. #define __timslib__menu_h
  37.  
  38. /* DeskLib includes */
  39. #include "Core.h"
  40. #include "DeskLib.Wimp.h"
  41.  
  42. typedef int menu;
  43.  
  44. /* The following is for use inside menu makers - it is TRUE if the menu is being
  45.    shown because it is being recreated due to an adjust click by the user.
  46.    FALSE at all other times.
  47. */
  48. extern BOOL menu_adjust_pressed;
  49.  
  50. /* The next two variables will indicate where the current menu came from.
  51.  
  52.    This is so that if you have a lot of similar menus attached to icons, you
  53.    don't have to bother remembering in your code where exactly the user clicked
  54.    to get this menu, and so all your handlers can be the same.
  55.    After all, this is where this information ought to be - it's the Menu module
  56.    that gets told about menu requests.
  57.  
  58.    When a menu is not open, or about to be opened, the value of these variables
  59.    will be undefined.  This is because the Wimp doesn't always explicitly tell the
  60.    application when a menu is closed - e.g. when user clicks outside a menu to close
  61.    it.
  62.  
  63.    Therefore stick to accessing them in your menu selection handlers or menu
  64.    makers.  Obviously, these variables are not updated if you just use Menu_Show
  65.    and don't use Menu_AttachMenu{Maker}.
  66. */
  67. extern window_handle menu_current_window;
  68. extern icon_handle   menu_current_icon;
  69.  
  70.  
  71. extern menu Menu_New(char *name, char *desc);
  72. /*
  73.   Creates a menu with the given name and description.  The description syntax
  74.   is the same as for RISC_OSLib's menu module.
  75. */
  76.  
  77. extern menu Menu_ColourMenu(char *title, char *last_item);
  78. /*
  79.   Creates a 16-colour menu, with an optional last item, e.g. call with "None" or 
  80.   "Transparent".  This entry is separated from the others by a dotted line.
  81.  
  82.   Pass NULL as last_item if you just want colours 0-15 with no special last field.
  83.   NB Don't pass the empty string ( "" ) - it won't work - you'll just get an empty
  84.   last field on the menu which will look real stoopid.
  85.  
  86.   Menu is created as a standard 'menu' type as used throughout this module, so
  87.   use Menu_Dispose() when you don't need it any more.
  88. */
  89.  
  90. extern void Menu_Dispose(menu the_menu, BOOL recursive);
  91. /*
  92.   De-allocates memory associated with this menu.  If recursive is TRUE, also
  93.   recursively de-allocates all sub-menus of the_menu.
  94. */
  95.  
  96. extern void Menu_SubMenu(menu parent, int entry, menu submenu);
  97. /*
  98.   Attaches 'submenu' as a sub-menu onto the menu 'parent' at position 'entry'.
  99. */
  100.  
  101. extern void Menu_AddDialogBox(menu the_menu, int entry, window_handle window);
  102. /*
  103.   Attaches a window (dialogue box) as a submenu onto 'the_menu' at position
  104.   'entry'.  Usually called for a menu warning event, just before dbox is
  105.   shown.
  106. */
  107.  
  108. extern void Menu_SetFlags(menu the_menu, int entry, BOOL tick, BOOL fade);
  109. /*
  110.   This sets the flags on the given menu entry.
  111. */
  112.  
  113. #define Menu_TickEntry(the_menu, entry) ((((menu_item *) (Menu_SysHandle(the_menu) + 1))[(entry)].menuflags.data.ticked) = TRUE)
  114. #define Menu_UnTickEntry(the_menu, entry) ((((menu_item *) (Menu_SysHandle(the_menu) + 1))[(entry)].menuflags.data.ticked) = FALSE)
  115.  
  116. #define Menu_FadeEntry(the_menu, entry) ((((menu_item *) (Menu_SysHandle(the_menu) + 1))[(entry)].iconflags.data.shaded) = TRUE)
  117. #define Menu_UnFadeEntry(the_menu, entry) ((((menu_item *) (Menu_SysHandle(the_menu) + 1))[(entry)].iconflags.data.shaded) = FALSE)
  118. /*
  119.   void Menu_TickEntry(menu the_menu, int entry)
  120.   void Menu_UnTickEntry(menu the_menu, int entry)
  121.   void Menu_FadeEntry(menu the_menu, int entry)
  122.   void Menu_UnFadeEntry(menu the_menu, int entry)
  123.  
  124.   These are simple(!) macros for when you want to set the tick or fade flags on
  125.   their own.
  126. */
  127.  
  128.  
  129. extern void Menu_MakeWritable(menu the_menu, int entry, 
  130.                         char *buffer, int bufferlength, char *validation);
  131. /*
  132.   This makes the specified menu entry writable.  It preserves the text currently
  133.   in the menu item - it is copied into 'buffer'.
  134. */
  135.  
  136. extern void Menu_Show(menu the_menu, wimp_point mouse_pos, BOOL iconbar);
  137. /*
  138.   This is used in response to a mouse button event with buttons = 4 (MENU
  139.   pressed).  The mouse_pos is used to position the menu - just pass the wimp_point
  140.   from the mouse button event straight through.
  141.   If iconbar is TRUE, it sets the vertical position correctly for an icon
  142.   bar menu as per the Acorn guideline in RO2 PRMs p1315 - 96 OS units above the
  143.   bottom of the screen.
  144. */
  145.  
  146. /*
  147.  
  148. extern menu_ptr Menu_SysHandle(menu the_menu);
  149.  
  150.   Returns a low-level handle to the menu, for manipulations not supported by
  151.   this module.
  152.  
  153.   NB. Do NOT use free() on this pointer - it won't work!
  154. */
  155. #define Menu_SysHandle(menu) ((menu_ptr) (menu))
  156.  
  157. /* Attaching menus for automatic handling */
  158.  
  159. typedef void (*menu_handler)(void *reference, int *hit);
  160. typedef menu (*menu_maker)(void *reference);
  161.  
  162. /* menu_selection: This variable indicates if an event is as a result of a menu
  163.    selection or submenu activation - use it inside your 'menu_handler()'.
  164.     TRUE => User actively clicked select/adjust on an item.
  165.    FALSE => User followed submenu arrow which generated a menu warning event.
  166.             (Use the '>' option to request menu warning events for items)
  167.  
  168.    This variable will hold the value 'TRUE' if accessed when menu handlers are
  169.    not being called, which is the logical value. e.g. if a hot-key is used to
  170.    open a dbox that would normally hang off a menu, it would behave as if the
  171.    parent entry of the dbox had been selected by the user, which would cause the
  172.    correct behaviour - i.e. dbox should open under the pointer.
  173. */
  174. extern BOOL menu_selection;
  175.  
  176. /* menu_submenupos: This variable holds the position passed by any MenuWarning
  177.    messages.  This means if you want to do your own opening of sub-menus - e.g.
  178.    custom dialogue boxes etc, just pass this position to Wimp_CreateSubMenu.
  179.    The contents if this variable are undefined if used while a MenuWarn message
  180.    is not being processed (use menu_selection - see above - to find out).
  181. */
  182. extern wimp_point menu_submenupos;
  183.  
  184. extern void Menu_AttachMenu(menu the_menu, window_handle window, icon_handle icon,
  185.                             menu_handler handler, void *reference);
  186. /*
  187.    the_menu  the menu to attach
  188.    window    should be event_ANY  - if not window specific, or
  189.              a window handle      - to attach only to that window
  190.    icon      should be event_ANY  - if not icon-specific, or
  191.              an icon handle       - to attach ONLY to that icon
  192.              (NOTE: if icon != event_ANY, window MUST be defined)
  193.   
  194.    handler   is the address of your menu handler function
  195.    reference is a handle for any user-data you want passed to the
  196.                 function whenever it is called.
  197.  
  198.    Note that menus attached to icons will be invoked by SELECT clicks as well
  199.    as MENU clicks.
  200. */  
  201.  
  202.  
  203. extern void Menu_AttachMenuMaker(menu_maker maker_proc, 
  204.                                  window_handle window, icon_handle icon,
  205.                                  menu_handler handler, void *reference);
  206. /*
  207.    the_menu  the menu to attach
  208.    window    should be event_ANY  - if not window specific, or
  209.              a window handle      - to attach only to that window
  210.    icon      should be event_ANY  - if not icon-specific, or
  211.              an icon handle       - to attach ONLY to that icon
  212.              (NOTE: if icon != event_ANY, window MUST be defined)
  213.   
  214.    handler   is the address of your menu handler function
  215.    reference is a handle for any user-data you want passed to the
  216.                 function whenever it is called.
  217.  
  218.    Note that menus attached to icons will be invoked by SELECT clicks as well
  219.    as MENU clicks.
  220. */
  221.  
  222. extern void Menu_AddDynamicDialogBox(window_handle window);
  223. /*
  224.   This is used for sub-menu dialog boxes that are created on demand.
  225.  
  226.   This should be called from within the menu selection handler when
  227.   a submenu is traversed that has been marked with a '>' option in the
  228.   menu string.  The handler should create the window to show as a submenu
  229.   (but not open it) and pass the handle to this function, then return.
  230.   The rest is automagic!
  231. */
  232.  
  233.  
  234. extern void Menu_DetachMenu(window_handle window, icon_handle icon);
  235. /*
  236.    Detaches any menus or menu makers from the given window/icon.
  237.    If called for a window, detaches *all* handlers for it, including
  238.    icon specific ones.
  239.    If the window is event_ANY, only removes the 'catch-all' handler - it
  240.    does NOT remove all menu handlers.
  241.  
  242.    It is legal to call this even if no menus/makers are attached to the
  243.    specified window/icon.
  244.  
  245.    window    should be event_ANY  - if not window specific, or
  246.              a window handle      - to detach only from that window
  247.    icon      should be event_ANY  - if not icon-specific, or
  248.              an icon handle       - to detach ONLY from that icon
  249.              (NOTE: if icon != event_ANY, window MUST be defined)
  250. */
  251.  
  252. #endif
  253.