home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / Dialog < prev    next >
Encoding:
Text File  |  1996-05-21  |  9.6 KB  |  299 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.01 (02 Mar 1994)
  14.     Purpose: Very high-level window (dialogue box) handling
  15. */
  16.  
  17. #ifndef __Desk_Dialog_h
  18. #define __Desk_Dialog_h
  19.  
  20. #ifdef __cplusplus
  21.     extern "C" {
  22. #endif
  23.  
  24.  
  25. #ifndef __Desk_Wimp_h
  26.     #include "Wimp.h"
  27. #endif
  28.  
  29. #ifndef __Desk_Window_h
  30.     #include "Window.h"
  31. #endif
  32.  
  33.  
  34. /*K**************************************************************************
  35.  
  36. > Dialog Boxes
  37.  
  38.  
  39.   A dialog box is a window that is popped open to get user choices and
  40.   then goes away - They can act like menus (go away when you click outside
  41.   them) if opened with Desk_Dialog_Show(), or can be permanent windows if
  42.   you open them using Desk_Dialog_ShowStatic().
  43.   This code simplifies popping up such dialogs, as it handles opening,
  44.   closing and simple processing of the window for you.
  45.  
  46.   To use Dialog, you do something like the following:
  47.   (Assuming a window where icon 0 is the 'OK' button, and icon 1 is the
  48.    'Cancel' button)
  49.  
  50.   {
  51.     dialog dlog;
  52.  
  53.     dlog = Desk_Dialog_Create("template", 0);           // Create the window
  54.     Desk_Dialog_ShowStatic(dlog, Desk_open_UNDERPOINTER);    // Pop up under pointer
  55.  
  56.     while (Desk_Dialog_WaitForClick(dlog) > 1 || Desk_Dialog_Persist(dlog))
  57.       |* Busy wait loop *| ;                       // Wait for OK/Cancel
  58.  
  59.     Desk_Window_Hide(dlog);      // Hide the window before we start processing
  60.  
  61.     if (Desk_Dialog_LastClicked(dlog) == 0)
  62.       ProcessTheData();     // OK was clicked, so go ahead with processing
  63.  
  64.     Desk_Dialog_Destroy(dlog);
  65.   }
  66.  
  67.  
  68.   SeeAlso:  Desk_dialog_record; dialog
  69.  
  70. ****************************************************************************/
  71.  
  72.  
  73.  
  74. typedef struct
  75.   {
  76.     Desk_window_handle window;         /* The window handle of this dialog      */
  77.  
  78.     Desk_icon_handle   lastclicked;    /* The icon handle of the last icon that
  79.                                    * was clicked, or Desk_dialog_NOCHOICE if no
  80.                                    * icons have been clicked yet.
  81.                                    */
  82.  
  83.     Desk_button_state  button;         /* The button state for the last
  84.                                    * click event.
  85.                                    */
  86.     struct
  87.     {
  88.       unsigned int stillopen : 1; /* The dialogue window is still open     */
  89.  
  90.       unsigned int persist   : 1; /* It should persist (adjust was clicked)*/
  91.  
  92.       unsigned int isstatic  : 1; /* It is a static (permanent) dialogue   */
  93.     } state;
  94.   } Desk_dialog_record;
  95. /*
  96.   Purpose:  Encapsulate the information pertaining to a particular dialog
  97.             box.  It records the dialog box's current state, and details
  98.             of the last event it received.
  99.   SeeAlso:  dialog; Dialog Boxes
  100. */
  101.  
  102.  
  103.  
  104. typedef Desk_dialog_record *dialog;
  105. /*
  106.   Purpose:  The usual type passed to Dialog functions.  The Desk_dialog_record
  107.             type specifies the information contained therein.
  108.   SeeAlso:  Desk_dialog_record; Dialog Boxes
  109. */
  110.  
  111.  
  112.  
  113.  
  114. #define Desk_dialog_CLOSE    ((Desk_icon_handle) -1)
  115. /*
  116.   MACRO:    Constant: Desk_dialog_CLOSE
  117.  
  118.   Purpose:  Used by Desk_Dialog_WaitForClick to signify when the user causes the
  119.             dialog box to be closed by click outside the window or clicking
  120.             on a close icon.
  121.   SeeAlso:  Desk_Dialog_WaitForClick
  122. */
  123.  
  124.  
  125.  
  126. #define Desk_dialog_NOCHOICE ((Desk_icon_handle) -2)
  127. /*
  128.   MACRO:    Constant: Desk_dialog_NOCHOICE
  129.  
  130.   Purpose:  The setting returned by Desk_Dialog_LastClicked() when the user has
  131.             not yet done anything (i.e. no icons have been clicked and the
  132.             window is open)
  133.   SeeAlso:  Desk_Dialog_LastClicked
  134. */
  135.  
  136.  
  137.  
  138. extern dialog Desk_Dialog_Create(char *Desk_template_name, int maxtitlesize);
  139. /*
  140.   Inputs:   Desk_template_name - the name of the window template to use in
  141.                             constructing the dialog box.
  142.             maxtitlesize  - the maximum space to reserve for the dialog box
  143.                             title bar (See Desk_Window_Create for more details).
  144.   Returns:  dialog - the newly created dialog box, or NULL if it was not
  145.                      possible to create the dialog.
  146.   Purpose:  Creates (but does not show) a dialog box from a named template.
  147.   Errors:   Out of memory; Could not find window template
  148.   SeeAlso:  Desk_Window_Create; Desk_Dialog_Show; Desk_Dialog_ShowStatic
  149. */
  150.  
  151.  
  152.  
  153. extern void Desk_Dialog_Destroy(dialog d);
  154. /*
  155.   Inputs:   d - the dialog box to destroy.
  156.   Purpose:  Removes from display and deletes a dialog box structure.
  157.             NOTE that the dialog structure is free'd by this, so you cannot
  158.             call any dialog functions (except Create of course) with it
  159.             after a Destroy.
  160.   SeeAlso:  Desk_Dialog_Create; Desk_Dialog_Hide
  161. */
  162.  
  163.  
  164.  
  165.  
  166. extern void Desk_Dialog_Show(dialog d);
  167. /*
  168.   Inputs:   d - the dialog box to show.
  169.   Purpose:  Shows a dialog box in the centre of the screen, as a submenu
  170.             window. (i.e. clicking outside the window or pressing escape
  171.             will remove it)
  172.   SeeAlso:  Desk_Dialog_ShowAt; Desk_Dialog_ShowStatic
  173. */
  174.  
  175.  
  176.  
  177. extern void Desk_Dialog_ShowAt(dialog d, int x, int y);
  178. /*
  179.   Inputs:   d    - the dialog to show.
  180.             x, y - the position to show the window at (top-left of window
  181.                    area).
  182.   Purpose:  Shows a dialogue box at a specified position. (i.e. clicking
  183.             outside the window or pressing escape will remove it)
  184.   SeeAlso:  Desk_Dialog_Show; Desk_Dialog_ShowStatic
  185. */
  186.  
  187.  
  188.  
  189.  
  190. extern void Desk_Dialog_ShowStatic(dialog d, Desk_window_openpos openpos);
  191. /*
  192.   Inputs:   d - the dialog to show.
  193.             openpos - where to show the dialog.
  194.   Purpose:  As Desk_Dialog_Show(), but more permanent - only a click on the close
  195.             icon (if present) will close it.  Of course it may be closed by
  196.             other means if the application assigns special meaning to an
  197.             icon  - e.g. a cancel button - and closes it itself when this
  198.             icon is clicked on.
  199.             Opens the window at the position requested (see Window.h), of:
  200.               Desk_open_ WHEREVER, CENTERED, OVERCARET, UNDERPOINTER, NEARLAST
  201.  
  202.             (It is very convenient if dialogs always appear under the mouse
  203.             pointer especially as mouse-movement distances (screen sizes)
  204.             increase.)
  205.   SeeAlso:  Desk_Dialog_Show; Desk_Dialog_ShowAt
  206. */
  207.  
  208.  
  209.  
  210. extern void Desk_Dialog_Hide(dialog d);
  211. /*
  212.   Inputs:   d - the dialog to hide.
  213.   Purpose:  Hides the dialog box by closing the window, but does not
  214.             destroy it.
  215.             Subsequent calls to Desk_Dialog_Show[Static] will work correctly.
  216.   SeeAlso:  Desk_Dialog_Show; Desk_Dialog_Destroy
  217. */
  218.  
  219.  
  220.  
  221. extern int Desk_Dialog_WaitForClick(dialog d);
  222. /*
  223.   Inputs:   d - the dialog to process click events for.
  224.   Returns:  The handle of the icon clicked, or Desk_dialog_CLOSE.
  225.   Purpose:  Waits for an icon to be clicked in the dialogue box.  All other
  226.             events are processed as usual.  If the user closes the window,
  227.             Desk_dialog_CLOSE is returned.
  228.             Note that Desk_Dialog_LastClicked can be called at any time up until
  229.             you call Desk_Dialog_Destroy() to find out what the last valid icon
  230.             click was (i.e. the last positive value that Desk_Dialog_WaitForClick
  231.             returned)
  232.   SeeAlso:  Desk_Dialog_LastClicked
  233. */
  234.  
  235.  
  236.  
  237. #define Desk_Dialog_WindowHandle(d) ((d)->window)
  238. /*
  239.   MACRO:    Desk_window_handle Desk_Dialog_WindowHandle(dialog d)
  240.  
  241.   Inputs:   d - the dialog in question.
  242.   Returns:  Window handle of the dialog.
  243.   Purpose:  Obtain the RISC OS Wimp window handle associated with this
  244.             dialog box.  This allows filling in of fields using, e.g.
  245.             DeskLib's 'Icon' module.
  246. */
  247.  
  248.  
  249.  
  250. #define Desk_Dialog_Persist(D) ((D)->state.persist && (D)->lastclicked >= 0)
  251. /*
  252.   MACRO:    Desk_bool Desk_Dialog_Persist(dialog d);
  253.  
  254.   Inputs:   d - the dialog to be checked for persistence.
  255.   Returns:  Desk_bool_TRUE if the last choice made on this dialog was made using
  256.             'adjust' - i.e. the user wants the dialog to stay open;
  257.             Desk_bool_FALSE otherwise.
  258.   Purpose:  Find out if the user wants the dialog to stay open after a
  259.             click event.
  260.             Unlike RISC OS Lib, this remembers the last click rather than
  261.             just checking if Adjust is down when called, so will work even
  262.             after an indentation delay.
  263.   SeeAlso:  Desk_Dialog_LastClicked; Desk_Dialog_StillOpen
  264. */
  265.  
  266.  
  267.  
  268. #define Desk_Dialog_LastClicked(D) ((D)->lastclicked)
  269. /*
  270.   MACRO:    Desk_icon_handle Desk_Dialog_LastClicked(dialog d);
  271.  
  272.   Inputs:   d - the dialog to check for the click event.
  273.   Returns:  The handle of the icon that was last clicked on this dialog,
  274.             or Desk_dialog_NOCHOICE if the user has not yet clicked an icon.
  275.   Purpose:  find out the last icon clicked on by the user in this dialog.
  276.   SeeAlso:  Desk_Dialog_Persist; Desk_Dialog_StillOpen
  277. */
  278.  
  279.  
  280.  
  281. #define Desk_Dialog_StillOpen(D) ((D)->state.stillopen)
  282. /*
  283.   MACRO:    Desk_bool Desk_Dialog_StillOpen(dialog d)
  284.  
  285.   Inputs:   d - the dialog to check.
  286.   Returns:  Desk_bool_TRUE if the dialog box is still open on screen;
  287.             Desk_bool_FALSE otherwise.
  288.   Purpose:  Find out if a dialog box is still open or not.
  289.   SeeAlso:  Desk_Dialog_Persist; Desk_Dialog_LastClicked.
  290. */
  291.  
  292.  
  293. #ifdef __cplusplus
  294. }
  295. #endif
  296.  
  297.  
  298. #endif
  299.