home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 2 / DATAFILE_PDCD2.iso / utilities2 / desklib / !DeskLib / h / Dialog < prev    next >
Encoding:
Text File  |  1993-07-10  |  6.1 KB  |  176 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:    Dialog.h
  12.     Author:  Copyright © 1993 Tim Browse, with modifications by JW
  13.     Version: 1.00 (10 Jul 1993)
  14.     Purpose: Very high-level window (dialogue box) handling
  15. */
  16.  
  17. #ifndef __dl_dialog_h
  18. #define __dl_dialog_h
  19.  
  20. #ifndef __dl_wimp_h
  21. #include "Wimp.h"
  22. #endif
  23.  
  24. #ifndef __dl_window_h
  25. #include "Window.h"
  26. #endif
  27.  
  28.  
  29. /*  A dialogue is a window that is popped open to get user choices and
  30.  *  then goes away - They can act like menus (go away when you click outside
  31.  *  them) if opened with Dialog_Show(), or can be permanent windows if
  32.  *  you open them using Dialog_ShowStatic().
  33.  *  This code simplifies popping up such dialogues, as it handles opening,
  34.  *  closing and simple processing of the window for you.
  35.  *
  36.  *  To use Dialog, you do something like the following:
  37.  *  (Assuming a window where icon 0 is the 'OK' button, and icon 1 is the
  38.  *   'Cancel' button)
  39.  *
  40.  *  {
  41.  *    dialog dlog;
  42.  *
  43.  *    dlog = Dialog_Create("template", 0);           |* Create the window    *|
  44.  *    Dialog_ShowStatic(dlog, open_UNDERPOINTER);    |* Pop up under pointer *|
  45.  *
  46.  *    while (Dialog_WaitForClick(dlog) > 1 || Dialog_Persist(dlog))
  47.  *      |* Busy wait loop *| ;                       |* Wait for OK/Cancel   *|
  48.  *
  49.  *    Window_Hide(dlog);      |* Hide the window before we start processing  *|
  50.  *
  51.  *    if (Dialog_LastClicked(dlog) == 0)
  52.  *      ProcessTheData();     |* OK was clicked, so go ahead with processing *|
  53.  *
  54.  *    Dialog_Destroy(dlog);
  55.  *  }
  56.  */
  57.  
  58.  
  59. typedef struct
  60. {
  61.   window_handle window;         /* The window handle of this dialogue window */
  62.   icon_handle   lastclicked;    /* The icon handle of the last icon that was
  63.                                  * clicked, or dialog_NOCHOICE if no icons
  64.                                  * have been clicked yet.
  65.                                  */
  66.   struct
  67.   {
  68.     unsigned int stillopen : 1;    /* The dialogue window is still open      */
  69.     unsigned int persist   : 1;    /* It should persist (adjust was clicked) */
  70.     unsigned int isstatic  : 1;    /* It is a static (permanent) dialogue    */ 
  71.   } state;
  72. } dialog_record;
  73.  
  74. typedef dialog_record *dialog;
  75.  
  76.  
  77. /*  Returned by Dialog_WaitForClick when user causes dialogue box to be
  78.  *  closed by clicking outside window or clicking on close icon.
  79.  */
  80. #define dialog_CLOSE    ((icon_handle) -1)
  81.  
  82.  
  83. /*  The setting returned by Dialog_LastClicked() when the user has not yet
  84.  *  done anything (i.e. no icons have been clicked and the window is open)
  85.  */
  86. #define dialog_NOCHOICE ((icon_handle) -2)
  87.  
  88.  
  89.   /*  Dialog_Create
  90.    *  Creates (but does not show) a dialog box from a named template.
  91.    */
  92. extern dialog Dialog_Create(char *template_name, int maxtitlesize);
  93.  
  94.  
  95.   /*  Dialog_Destroy
  96.    *  Removes from display and deletes a dialogue box structure.
  97.    *  NOTE that the dialog structure is free'd by this, so you cannot call
  98.    *  any dialogue functions (except Create of course) with it after a Destroy
  99.    */
  100. extern void Dialog_Destroy(dialog d);
  101.  
  102.  
  103.   /*  Dialog_Show
  104.    *  Shows a dialogue box in the centre of the screen, as a submenu window.
  105.    *  (i.e. clicking outside the window or pressing escape will remove it)
  106.    */
  107. extern void Dialog_Show(dialog d);
  108.  
  109.  
  110.   /*  Dialog_ShowStatic
  111.    *  As Dialog_Show(), but more permanent - only a click on the close icon
  112.    *  (if present) will close it.  Of course it may be closed by other means
  113.    *  if the application assigns special meaning to an icon  - e.g. a cancel
  114.    *  button - and closes it itself when this icon is clicked on.
  115.    *  Opens the window at the position requested (see Window.h), of:
  116.    *    open_ WHEREVER, CENTERED, OVERCARET, UNDERPOINTER, NEARLAST
  117.    *
  118.    *  (It is very convenient if dialogues always appear under the mouse pointer
  119.    *  especially as mouse-movement distances (screen sizes) increase)
  120.    */
  121. extern void Dialog_ShowStatic(dialog d, window_openpos openpos);
  122.  
  123.  
  124.   /*  Dialog_WaitForClick
  125.    *  Waits for an icon to be clicked in the dialogue box.  All other events
  126.    *  are processed as usual.  If the user closes the window, dialog_CLOSE
  127.    *  is returned.
  128.    *  Note that Dialog_LastClicked can be called at any time up until you call
  129.    *  Dialog_Destroy() to find out what the last valid icon click was (i.e.
  130.    *  the last positive value that WaitForClick returned)
  131.    */
  132. extern int Dialog_WaitForClick(dialog d);
  133.  
  134.  
  135.   /*  Dialog_WindowHandle
  136.    *  Returns the RISC OS Wimp window handle associated with this dialogue box.
  137.    *  This allows filling in of fields using, e.g. DeskLib's 'Icon' module.
  138.    *
  139.    *    extern window_handle Dialog_WindowHandle(dialog d);
  140.    */
  141. #define Dialog_WindowHandle(D) ((D)->window)
  142.  
  143.  
  144.   /*  Dialog_Persist
  145.    *  Returns TRUE if the last choice made for this dialogue box was made with
  146.    *  adjust, and the dialogue window is still open - i.e. the user wants
  147.    *  the dialogue to stay open.
  148.    *  Unlike RISC OS Lib, this remembers the last click rather than just
  149.    *  checking if Adjust is down when called, so will work even after an
  150.    *  indentation delay.
  151.    *
  152.    *    extern BOOL Dialog_Persist(dialog d);
  153.    */
  154. #define Dialog_Persist(D) ((D)->state.persist && (D)->lastclicked >= 0)
  155.  
  156.  
  157.   /*  Dialog_LastClicked
  158.    *  Returns the icon number of the last icon which was clicked in the
  159.    *  dialogue window. If no icons have been clicked yet, returns
  160.    *  dialog_NOCHOICE.
  161.    *
  162.    *    extern icon_handle Dialog_LastClicked(dialog d);
  163.    */
  164. #define Dialog_LastClicked(D) ((D)->lastclicked)
  165.  
  166.  
  167.   /*  Dialog_StillOpen
  168.    *  Returns TRUE if the dialogue window is still open
  169.    *
  170.    *   extern BOOL Dialog_StillOpen(dialog d);
  171.    */
  172. #define Dialog_StillOpen(D) ((D)->state.stillopen)
  173.  
  174.  
  175. #endif
  176.