home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / Dialog2 < prev    next >
Encoding:
Text File  |  1997-01-20  |  12.5 KB  |  361 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:    Dialog2.h
  12.     Author:  Copyright © 1994 Julian Smith
  13.     Version: 1.03 (13 Mar 1995)
  14.     Purpose: Dialogue box handling
  15.     Mods:    25 Feb 1995 - JPS - Added okfn which is called when program should
  16.                                  read the dialog's contents
  17.              13 Mar 1995 - JPS - Split up source a bit more so that less code
  18.                                  would be linked in.
  19.                                  Bugfix: Desk_Event_ReleaseWindow now called when
  20.                                  window isn't deleted.
  21.              10 Apr 1995 - JPS - Modified to support DLLs with the global
  22.                                  variable '*Desk_dialog2_menublock'.
  23. */
  24.  
  25.  
  26. #ifndef __Desk_Dialog2_h
  27. #define __Desk_Dialog2_h
  28.  
  29. #ifdef __cplusplus
  30.     extern "C" {
  31. #endif
  32.  
  33.  
  34. #ifndef __Desk_Wimp_h
  35.     #include "Wimp.h"
  36. #endif
  37.  
  38. #ifndef __Desk_Window_h
  39.     #include "Window.h"
  40. #endif
  41.  
  42.  
  43.  
  44. typedef enum    {
  45.     Desk_dialog2_type_CLOSED    = 0,
  46.     Desk_dialog2_type_MENULEAF,
  47.     Desk_dialog2_type_MENU,
  48.     Desk_dialog2_type_STATIC
  49.     }
  50.     Desk_dialog2_dialog2type;
  51.  
  52.  
  53. typedef struct Desk_dialog2_block *Desk_dialog2_blockptr;
  54.  
  55. typedef void (*Desk_dialog2_openfn)( Desk_dialog2_blockptr);
  56. typedef void (*Desk_dialog2_okfn)( Desk_dialog2_blockptr);
  57.  
  58.  
  59. typedef struct Desk_dialog2_block    {
  60.  
  61.     void        *reference;    /* This is supplied by you.        */
  62.     const char    *templatename;    /* Name in the Templates file of the     */
  63.                     /* window associated with this dialog2    */
  64.     Desk_window_handle    window;        /* This is NULL whenever the window has been deleted.    */
  65.  
  66.     Desk_dialog2_openfn    openfn;        /* Your function, called whenever a dialog2 is opened.    */
  67.     Desk_dialog2_okfn    okfn;        /* Called when OK is clicked, or return-in-last-icon    */
  68.                     /* ie whenver the dialog's contents need acting on.    */
  69.     union    {
  70.         int    value;
  71.         struct    {
  72.             unsigned int    type        :  2;    /* A Desk_dialog2_dialog2type    */
  73.             unsigned int    keepwindow    :  1;
  74.             unsigned int    notifyclose    :  1;
  75.             int        okbutton    :  9;
  76.             int        cancelbutton    :  9;
  77.             int        maxtitlesize    : 10;
  78.             }
  79.             data;
  80.         }
  81.         flags;
  82.     }
  83.     Desk_dialog2_block;
  84. /*
  85.  
  86. This structure holds all the information about a particular dialog box.
  87. All the fields are all set initially by Desk_Dialog2_CreateDialogBlock - you
  88. shouldn't need to change them normally.
  89.  
  90. If you do have to change things yourself, you should *not* change any
  91. fields directly, as some need to be modified only by internal Desk_Dialog2_
  92. functions. There are a few macros/functions below which give you as much
  93. access as is good for you! See the end of this file for details of what
  94. the fields mean.
  95.  
  96. */ 
  97.  
  98.  
  99.  
  100. /* Here come the functions:    */
  101.  
  102. Desk_dialog2_block    *Desk_Dialog2_CreateDialogBlock( 
  103.     const char        *templatename, 
  104.     Desk_icon_handle    okbutton,
  105.     Desk_icon_handle    cancelbutton,
  106.     Desk_dialog2_openfn    openfn,
  107.     Desk_dialog2_okfn    okfn,
  108.     void            *reference
  109.     );
  110. /* 
  111.  
  112. This creates a dialog box information block. Store the returned pointer
  113. and pass it to Desk_Dialog2_OpenDialogStatic, Desk_Dialog2_OpenDialogMenu or
  114. Desk_Dialog2_OpenDialogMenuLeaf as/when the dialog box is required.
  115.  
  116. 'templatename' should be the name of the dialog window in your templates
  117. file.  Desk_Dialog2_CreateDialogBlock doesn't copy this string, it just
  118. stores the address of the start of the string, so the string you pass
  119. should be a permanent one, eg Desk_Dialog2_CreateDialogBlock( "infowindow"...).
  120.  
  121. 'okbutton' and 'cancelbutton' should be the icon handles of the OK and
  122. cancel buttons in the window. Use -1 if these aren't present. The
  123. Dialog2 library will claim Desk_event_CLICKs, and call Desk_Dialog2_CloseDialog if
  124. there is a  SELECT click on either of these two buttons. It will also
  125. claim Desk_event_KEY and fake  a SELECT click on ok/cancel when Return/Escape
  126. is pressed (assuming that the validation strings for writable icons are
  127. set up properly - this is done automatically in !TemplEd, for example).
  128.  
  129.  
  130. 'openfn' is called whenever the dialog box is opened (unless 'openfn' is
  131. NULL). This is done after the type (menu, menuleaf, static) has been
  132. set, so 'openfn' will know what sort of dialog is being opened. 'openfn'
  133. should call Desk_Event_Claim for mouse-clicks etc so that your application
  134. can deal with clicks/keypresses in the dialog window. Note that all
  135. Desk_event_ handlers for the dialog window are released using Desk_Window_Delete
  136. when a dialog is closed (unless 'keepwindow' is set - see below), so 
  137. you can't be sure of getting dialog-window events unless you claim them
  138. in openfn  each time the dialog is opened.
  139.  
  140. 'openfn' should have a prototype like:
  141. void MyOpenDialog2Function( Desk_dialog2_block *dialog2);
  142.  
  143. The 'reference' passed to Desk_Dialog2_CreateDialogBlock will be in
  144. dialog2->reference.
  145.  
  146. Note.
  147. -----
  148.  
  149. If (as is normal) you claim Desk_event_CLICK in your 'openfn' (see below),
  150. you will  hear about clicks *before* the Dialog2 function, because
  151. Dialog2 calls Desk_Event_Claim  before calling 'openfn', and the Event module
  152. sends events to more recent  claiments first (also, the claim is for any
  153. icon on the window, so has lower  priority than specific-icon claims).
  154. Hence the dialog2 will be closed *after* you have dealt with OK/cancel
  155. clicks, which is what should happen.
  156.  
  157. If the auto-handling of OK/Cancel and Return/Escape bothers you, just
  158. pass -1 for the  two button handles, and Dialog2 will not interfere with
  159. button clicks or key-presses at all. You are then responsible for
  160. calling Desk_Dialog2_CloseDialog when an 'OK' or  'Cancel' button is clicked,
  161. or when Return/Escape is pressed.
  162.  
  163. */
  164.  
  165.  
  166.  
  167. /* The next few functions return ERROR or NOERROR.    */
  168. /* See DeskLib:Core.h) for #defines of (NO)ERROR.    */
  169.  
  170. void    Desk_Dialog2_OpenDialogMenuLeaf( Desk_event_pollblock *event, Desk_dialog2_block *dialog2);
  171. /* 
  172. Opens the dialog2 as the leaf of the current menu. This should be done
  173. in response  to a Desk_message_MENUWARN - the Desk_event_pollblock should be the
  174. one which is a Desk_message_MENUWARN.
  175. */
  176.  
  177. void    Desk_Dialog2_OpenDialogMenu( Desk_dialog2_block *dialog2, Desk_window_openpos openpos);
  178. /*
  179. Opens the dialog2 as a menu-dialogue - ie clicking outside it will
  180. make it disappear. This uses Desk_Wimp_CreateMenu.
  181. */
  182.  
  183. void    Desk_Dialog2_OpenDialogStatic( Desk_dialog2_block *dialog2, Desk_window_openpos openpos);
  184. /*
  185. Opens the dialog2 as a static dialog - ie a proper window. Returns
  186. NOERROR if succesful, or ERROR if unable to open the dialog2.
  187. */
  188.  
  189. void    Desk_Dialog2_CloseDialog( Desk_dialog2_block *dialog2);
  190. /*
  191. Closes the dialog. Can be called from (for eg) Desk_event_CLICK-handling code
  192. for a 'Cancel' button in the dialog2's window.
  193.  
  194. If dialog2->flags.data.keepwindow == 0 (the default), the dialog window
  195. will be Desk_Window_Delete-ed, so all handlers for the window will be
  196. released automatically.
  197.  
  198. If the dialog2 is part of a menu, the menu will be closed automaticlly.
  199. */
  200.  
  201.  
  202. void    Desk_Dialog2_DeleteDialog( Desk_dialog2_block *dialog2);
  203. /*
  204. This closes dialog2, if it was open, and then removes the dialog2 block
  205. completely, so you mustn't use 'dialog2' again after calling this
  206. function. 
  207.  
  208. Call this if you will never need to open the dialog ever again.    
  209. */
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220. /* 
  221. ********************************************************************
  222. ********************************************************************
  223. **Other information which you won't need to know about normally...**
  224. ********************************************************************
  225. ********************************************************************
  226. */
  227. /*
  228. dialog2->openfn;
  229.     This is a pointer to a function that is called whenever 
  230.     the dialog2 is opened, to allow the application to register 
  231.     Desk_Event_ handlers for mouse-clicks etc.
  232.     This function will also be called when the dialog2 is closed, 
  233.     if you set flags.value.notifyclose with Desk_Dialog2_SetNotifyClose.
  234.  
  235. dialog2->flags.data.type    : 2;
  236.     Treat as a Desk_dialog2_dialog2type, ie it is one of:
  237.     Desk_dialog2_type_CLOSED, Desk_dialog2_type_MENU, Desk_dialog2_type_MENULEAF
  238.     and Desk_dialog2_type_STATIC.
  239.     Useful if, for eg, you are thinging of opening a menu based 
  240.     on the dialog2 window.
  241.     You might not want to do this if the dialog2 box is already
  242.     a menu, or part of a menu. Also tells you if the dialog2
  243.     is closed.
  244.     *Don't* change 'type' yourself.
  245.  
  246. dialog2->flags.data.keepwindow    : 1;
  247.     If 0 (the default), Desk_Wimp_DeleteWindow will be called whenever 
  248.     the dialog2 is closed and 'window' set to NULL. Desk_Window_Create 
  249.     is called whenever the dialog2 is opened, with 'templatename'.
  250.     Hence 'window' will only be a proper window-handle when the 
  251.     dialog is open.
  252.     
  253.     If 1, the dialog2's window is left created at all times after 
  254.     the first time the dialog is opened.
  255.     
  256.     You can change 'keepwindow' at any time you please - use
  257.     the macro 'Desk_Dialog2_SetKeepWindow', #defined below.
  258.  
  259.     You should set 'keepwindow' if you want to have your own 
  260.     event handlers permanently attatched to the dialog2 window, 
  261.     without having to Desk_Event_Claim/Release every time the dialog2
  262.     is opened/closed.
  263.  
  264. dialog2->flags.data.notifyclose    : 1;
  265.     If 1, 'openfn' will also be called whenver the dialog
  266.     is closed. 'openfn' will know whether the dialog is being
  267.     opened/closed by looking at dialog2->flags.data.type, which 
  268.     will be Desk_dialog2_type_CLOSED if the dialog2 is closing.
  269.     
  270.     The reason for this is that you might want to register 
  271.     a non-window-specific event handler when the dialog2 is
  272.     open - this won't be released when the dialog window is
  273.     closed with Desk_Window_Delete().
  274.     
  275.     'notifyclose' is set to 0 initially by Desk_Dialog2_CreateDialogBox.
  276.     You can change it whenever you like - use the macro
  277.     'Desk_Dialog_SetNotifyClose' #defined below.
  278.  
  279. dialog2->flags.data.maxtitlesize    : 10;
  280.     This is initially set to Desk_template_TITLEMIN, and is passed to
  281.     Desk_Window_Create whenever the dialog2's window needes to be 
  282.     created. If you need to change the title of a Dialog2 window
  283.     to something longer than in the original templates file, you
  284.     should do this before the Dialog2's window is created, with
  285.     Desk_Dialog2_ChangeTitleSize.
  286. */
  287.  
  288.  
  289. /* These next few prototypes are probably not all that much use normally...    */
  290.  
  291.  
  292.  
  293.  
  294. #ifdef Desk__using_SDLS
  295.   extern Desk_dialog2_block    **Desk_Dialog2__Ref_menublock( void);
  296. #endif
  297.  
  298. #if defined( Desk__using_SDLS) && !defined( Desk__making_Dialog2)
  299.   #define Desk_dialog2_menublock (*Desk_Dialog2__Ref_menublock())
  300. #else
  301.   extern Desk_dialog2_block    *Desk_dialog2_menublock;
  302. /* 
  303. This will always point to the dialog2 which is open as part of a menu,
  304. or be NULL. If you call Desk_Dialog2_CloseDialog( Desk_dialog2_menublock) whenever
  305. you close a menu (ie a menu choice with Select or Menu), then this will
  306. free the dialog2.                            
  307. */
  308. #endif
  309.  
  310.  
  311.  
  312.  
  313. void    Desk_Dialog2_Window_GetWindowOpenPos( 
  314.         Desk_wimp_point *pos, Desk_window_openpos openpos, Desk_window_handle window
  315.         );
  316. /* 
  317. Makes 'pos' be the top-left of the window if it was opened with
  318. Desk_Window_Show. This actually opens the window using Desk_Window_Show, reads
  319. where the window was    opened, and closes the window.
  320. */
  321.  
  322. void    Desk_Dialog2_EnsureWindowHandle( Desk_dialog2_block *dialog2);
  323. /*
  324. Desk_Window_Create's a window for the Desk_dialog2_box if it hasn't got one already.
  325.  
  326. You can call this anytime - just be aware that Dialog2 will delete the
  327. window whenver the dialog closes, unless you have called
  328. Desk_Dialog2_KeepWindow.
  329. */
  330.  
  331. #define Desk_Dialog2_ChangeCloseNotification( dialog2, x)    (dialog2)->flags.data.notifyclose = (x)
  332. #define Desk_Dialog2_NotifyClose( dialog2)        Desk_Dialog2_ChangeCloseNotification( dialog2, 1)
  333. #define Desk_Dialog2_DontNotifyClose( dialog2)    Desk_Dialog2_ChangeCloseNotification( dialog2, 0)
  334. /* 
  335. Sets whether dialog2->openfn is called when the dialog is closed.
  336.  
  337. The default is not to do this. */
  338.  
  339.  
  340. #define Desk_Dialog2_ChangeKeepWindow( dialog2, x)    (dialog2)->flags.data.keepwindow = (x)
  341. #define Desk_Dialog2_KeepWindow( dialog2)        Desk_Dialog2_ChangeKeepWindow( dialog2, 1)
  342. #define Desk_Dialog2_DontKeepWindow( dialog2)    Desk_Dialog2_ChangeKeepWindow( dialog2, 0)
  343. /*
  344. Sets whether the dialog2's window is not deleted whenever the dialog2 is
  345. closed. The default is 0 - ie the window *is* deleted whenever the
  346. dialog is closed. */
  347.  
  348. #define Desk_Dialog2_ChangeTitleSize( dialog2, x)    (dialog2)->flags.data.maxtitlesize = (x)
  349. /*
  350. flags.data.maxtitlesize is passed to Desk_Window_Create. See
  351. DeskLib:Template.h for an explanation of what maxtitlesize is all
  352. about...
  353. */
  354.  
  355. #ifdef __cplusplus
  356. }
  357. #endif
  358.  
  359.  
  360. #endif
  361.