home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / Menu2 < prev    next >
Encoding:
Text File  |  1997-01-20  |  7.8 KB  |  273 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:    Menu2.h
  12.     Author:  Copyright © 1995 Julian Smith
  13.     Version: 1.00 (22 Jun 1995)
  14.     Purpose: Easy menu handling
  15.     History:
  16.              1.10 (29 Aug 1996)    Added closefn.
  17.              07 Jan 1997    Added helpfn.
  18. */
  19.  
  20.  
  21. #ifndef __Desk_Menu2_h
  22. #define __Desk_Menu2_h
  23.  
  24. #ifdef __cplusplus
  25.     extern "C" {
  26. #endif
  27.  
  28.  
  29. #ifndef __Desk_Menu_h
  30. #include "Desk.Menu.h"
  31. #endif
  32.  
  33.  
  34. /*
  35. Menu2
  36.  
  37. Menu2 provides a slightly higher-level interface to menus than the
  38. Menu library. It uses Menu functions. The application should
  39. supply up to four functions for each menu it uses. These functions are
  40. automatically called when required, to handle menu-choices, set
  41. menuflags, find submenus, and generate custom menus.
  42.  
  43. The Menu2 library automatically handles the re-opening of menus after an
  44. ADJUST choice, and also frees the menu data after a menu has closed.
  45.  
  46. If your app uses Menu2 then, when it starts up, it should call
  47. Desk_Menu2_Create for every menu it will use, and store the returned
  48. pointers.
  49.  
  50. These pointers are used to open menu in the future using Desk_Menu2_Open(),
  51. or to specify what submenu should be opened when required.
  52.  
  53. Note that Menu2 only creates menus when they are actually open, in order
  54. to save RMA memory.
  55.  
  56. There is also a function Desk_Menu2_AttachMenu which automatically opens
  57. menus in response to a click on an icon/window.
  58.  
  59. */
  60.  
  61.  
  62. typedef int    Desk_menu2_handle;
  63. /*
  64. This type is used to identify menus.
  65. */
  66.  
  67. typedef Desk_menu_ptr    (*Desk_menu2_makefn)( void *reference);
  68. /*
  69. This function-type should make a menu and return a pointer to it.
  70.  
  71. 'reference' is the reference originally passed to Desk_Menu2_Create for
  72. this menu.
  73.  */
  74.  
  75. typedef void    (*Desk_menu2_closefn)( Desk_menu_ptr menu, void *reference);
  76. /*
  77. This function-type is called when a menu is finished with (ie either a
  78. choice is made with 'Select' or 'Menu', or a Desk_message_MENUSDELETED
  79. message is received).
  80.  
  81. If a Desk_Menu2 menu has a makefn, you should provide a closefn which
  82. frees all data associated with the menu.
  83.  */
  84.  
  85. typedef void    (*Desk_menu2_flagsfn)( Desk_menu_ptr menu, void *reference);
  86. /*
  87. This function-type should set any flags in the menu. It will be called
  88. whenever the menu is created or reopened following an ADJUST
  89. menu-choice.
  90.  
  91. 'reference' is the reference originally passed to Desk_Menu2_Create for
  92. this menu.
  93.  */
  94.  
  95.  
  96. typedef void    (*Desk_menu2_selectfn)( int itemnum, void *reference);
  97. /*
  98. This function-type is called whenever a menu-choice is made. 'itemnum'
  99. determines the menu item-number which was chosen.
  100.  
  101. 'reference' is the reference originally passed to Desk_Menu2_Create for
  102. this menu.
  103.  
  104. Functions of this type shoule use globals such as Desk_Event_lastevent
  105. and Desk_menu_currentopen if they need to know more about the menu.
  106.  */
  107.  
  108. typedef Desk_menu2_handle    (*Desk_menu2_subfn)( int itemnum, Desk_event_pollblock *event, void *reference);
  109. /*
  110. This function-type is called whenever a submenu is required. 'itemnum'
  111. is the number of the menu item which needs a submenu, while 'event' is
  112. the original Desk_message_MENUWARN.
  113.  
  114. 'event' is included so that you can open a dialog box (or your own
  115. submenu menu) using the information in the Desk_message_menuwarn
  116. 'event->data.message.data.menuwarn'. If this is done, the function
  117. should return NULL, so that Menu2 knows that a submenu has been opened.
  118.  
  119. 'reference' is the reference originally passed to Desk_Menu2_Create for
  120. this menu.
  121.  */
  122.  
  123. typedef void    (*Desk_menu2_helpfn)( char* buffer, int buffsize, int itemnum, void *reference);
  124. /*
  125. This function should put 0-terminated help text into 'buffer' relevent
  126. for menu item 'itemnum'.
  127.  */
  128.  
  129.  
  130.  
  131.  
  132.  
  133. Desk_menu2_handle Desk_Menu2_Create( 
  134.     const char        *title,
  135.     const char        *spec,
  136.     Desk_menu2_makefn    makefn,     /* If !=NULL, called to make the menu    */
  137.     Desk_menu2_flagsfn    flagsfn,     /* Called every time menu is opened    */
  138.     Desk_menu2_subfn    subfn,         /* Called when submenu is needed    */
  139.     Desk_menu2_selectfn    selectfn,     /* Called when selection is made    */
  140.     Desk_menu2_closefn    closefn,    /* Called when menu is closed        */
  141.     void            *reference    /* Passed to the 5 fns above        */
  142.     );
  143. /*
  144. As Desk_Menu2_Create2, but doesn't expect a helpfn pointer.
  145.  */
  146.  
  147.  
  148. Desk_menu2_handle Desk_Menu2_Create2( 
  149.     const char        *title,
  150.     const char        *spec,
  151.     Desk_menu2_makefn    makefn,     /* If !=NULL, called to make the menu    */
  152.     Desk_menu2_flagsfn    flagsfn,     /* Called every time menu is opened    */
  153.     Desk_menu2_subfn    subfn,         /* Called when submenu is needed    */
  154.     Desk_menu2_selectfn    selectfn,     /* Called when selection is made    */
  155.     Desk_menu2_closefn    closefn,    /* Called when menu is closed        */
  156.     Desk_menu2_helpfn    helpfn,        /* Called when help is required        */
  157.     void            *reference    /* Passed to the 5 fns above        */
  158.     );
  159. /*
  160. This returns a unique handle for a menu.
  161.  
  162. Returns 0 if unable to make the menu - eg not enough memory.
  163.  
  164. If 'makefn' is NULL, the menu will be made, when required, from 'title'
  165. and 'spec' using Desk_Menu_New. Otherwise, 'title' and 'spec' are ignored,
  166. and the 'makefn' is relied apon to make the menu and return a pointer to
  167. it.
  168.  
  169. If not NULL, 'closefn' will be called when the menu is finished (ie a
  170. choice made with SELECT or MENU, or a Desk_message_MENUSDELETED is
  171. received).
  172.  
  173. If 'makefn' is NULL, Desk_Menu2 will free the menu itself, with
  174. Desk_Icon_DisposeIndData and Desk_DeskMem_Free. Otherwise, you should
  175. provide a 'closefn' which frees the data created by 'makefn'.
  176.  
  177. NB 'title' and 'spec' are *not* copied, so they must point to permanent
  178. strings, or be NULL, in which case makefn must not be NULL.
  179. */
  180.  
  181.  
  182.  
  183. Desk_menu2_handle    Desk_Menu2_CreateFromMsgs(
  184.             const char        *titletag,
  185.             const char        *spectag,
  186.             Desk_menu2_makefn    makefn,
  187.             Desk_menu2_flagsfn    flagsfn,
  188.             Desk_menu2_subfn    subfn,
  189.             Desk_menu2_selectfn    selectfn,
  190.             Desk_menu2_closefn    closefn,
  191.             Desk_menu2_helpfn    helpfn,
  192.             void            *reference
  193.             );
  194. /*
  195. Same as Desk_Menu2_Create, except the title and menu specification are read
  196. from a message file using Desk_Msgs_Lookup( titletag, ...) and Desk_Msgs_Lookup(
  197. spectag, ...) .
  198. */
  199.  
  200.  
  201. void    Desk_Menu2_Open( Desk_menu2_handle handle, int x, int y);
  202. /*
  203. This opens the specified menu. It uses Desk_Menu_Show, so use y=-1 if the
  204. menu is an iconbar menu.
  205. */
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212. void    Desk_Menu2_AttachMenu( 
  213.     Desk_window_handle    window, 
  214.     Desk_icon_handle    icon,
  215.     Desk_menu2_handle    menu,
  216.     int            button
  217.     );
  218. /*
  219. This uses Desk_Event_Claim to open a menu when the specified icon-window is
  220. clicked with the specified button(s). If the click is on the iconbar,
  221. the menu will be automatically opened in the correct position for
  222. iconbar menus.
  223.  
  224. Eg
  225.  
  226. Desk_Menu2_AttachMenu( w, i, specialmenu, Desk_button_MENU | Desk_button_SELECT);
  227. Desk_Menu2_AttachMenu( w, Desk_event_ANY, generalmenu, Desk_button_MENU);
  228.  
  229. See also: Desk_Menu2_DetachMenu.
  230. */
  231.  
  232.  
  233. void    Desk_Menu2_DetachMenu( 
  234.     Desk_window_handle    window, 
  235.     Desk_icon_handle    icon,
  236.     Desk_menu2_handle    menu,
  237.     int            button
  238.     );
  239. /*
  240. Stops the specified menu being opened when the icon-window is clicked
  241. with the specified button(s).
  242.  
  243. See also: Desk_Menu2_AttachMenu.
  244. */
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251. #ifdef Desk_DeskLib_DEBUG
  252.     #ifdef Desk__making_Menu2
  253.         #include "Debug.h"
  254.         #define Desk_debug_level Desk_menu2_debuglevel
  255.     #endif
  256.     
  257.     extern int    Desk_menu2_debuglevel;
  258. /*
  259. In the debug version of DeskLib, this is the Menu2 library's own
  260. version of Desk_debug_level. It is initially 0; a program can set it to
  261. different values to turn on different debug ouputs in the Menu2
  262. library.
  263.  */
  264. #endif
  265.  
  266.  
  267. #ifdef __cplusplus
  268. }
  269. #endif
  270.  
  271.  
  272. #endif
  273.