home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / desklib / !DeskLib / h / Dialog < prev    next >
Encoding:
Text File  |  1994-05-29  |  12.5 KB  |  364 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 __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. /*K**************************************************************************
  30.  
  31. > Dialog Boxes
  32.  
  33.  
  34.   A dialog box is a window that is popped open to get user choices and
  35.   then goes away - They can act like menus (go away when you click outside
  36.   them) if opened with Dialog_Show(), or can be permanent windows if
  37.   you open them using Dialog_ShowStatic().
  38.   This code simplifies popping up such dialogs, as it handles opening,
  39.   closing and simple processing of the window for you.
  40.  
  41.   To use Dialog, you do something like the following:
  42.   (Assuming a window where icon 0 is the 'OK' button, and icon 1 is the
  43.    'Cancel' button)
  44.  
  45.   {
  46.     dialog dlog;
  47.  
  48.     dlog = Dialog_Create("template", 0);           // Create the window
  49.     Dialog_ShowStatic(dlog, open_UNDERPOINTER);    // Pop up under pointer
  50.  
  51.     while (Dialog_WaitForClick(dlog) > 1 || Dialog_Persist(dlog))
  52.       |* Busy wait loop *| ;                       // Wait for OK/Cancel
  53.  
  54.     Window_Hide(dlog);      // Hide the window before we start processing
  55.  
  56.     if (Dialog_LastClicked(dlog) == 0)
  57.       ProcessTheData();     // OK was clicked, so go ahead with processing
  58.  
  59.     Dialog_Destroy(dlog);
  60.   }
  61.  
  62.  
  63.   SeeAlso:  dialog_record; dialog
  64.  
  65. ****************************************************************************/
  66.  
  67.  
  68.  
  69. /*T*************************************************************************/
  70.  
  71.   typedef struct
  72.   {
  73.     window_handle window;         /* The window handle of this dialog      */
  74.  
  75.     icon_handle   lastclicked;    /* The icon handle of the last icon that
  76.                                    * was clicked, or dialog_NOCHOICE if no
  77.                                    * icons have been clicked yet.
  78.                                    */
  79.  
  80.     button_state  button;         /* The button state for the last
  81.                                    * click event.
  82.                                    */
  83.     struct
  84.     {
  85.       unsigned int stillopen : 1; /* The dialogue window is still open     */
  86.  
  87.       unsigned int persist   : 1; /* It should persist (adjust was clicked)*/
  88.  
  89.       unsigned int isstatic  : 1; /* It is a static (permanent) dialogue   */
  90.     } state;
  91.   } dialog_record;
  92.  
  93. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  94.  
  95.   Purpose:  Encapsulate the information pertaining to a particular dialog
  96.             box.  It records the dialog box's current state, and details
  97.             of the last event it received.
  98.   SeeAlso:  dialog; Dialog Boxes
  99.  
  100. ****************************************************************************/
  101.  
  102.  
  103.  
  104. /*T*************************************************************************/
  105.  
  106.   typedef dialog_record *dialog;
  107.  
  108. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  109.  
  110.   Purpose:  The usual type passed to Dialog functions.  The dialog_record
  111.             type specifies the information contained therein.
  112.   SeeAlso:  dialog_record; Dialog Boxes
  113.  
  114. ****************************************************************************/
  115.  
  116.  
  117.  
  118.  
  119. /*M*************************************************************************/
  120.  
  121.   #define dialog_CLOSE    ((icon_handle) -1)
  122.  
  123. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  124.  
  125.   MACRO:    Constant: dialog_CLOSE
  126.  
  127.   Purpose:  Used by Dialog_WaitForClick to signify when the user causes the
  128.             dialog box to be closed by click outside the window or clicking
  129.             on a close icon.
  130.   SeeAlso:  Dialog_WaitForClick
  131.  
  132. ****************************************************************************/
  133.  
  134.  
  135.  
  136. /*M*************************************************************************/
  137.  
  138.   #define dialog_NOCHOICE ((icon_handle) -2)
  139.  
  140. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  141.  
  142.   MACRO:    Constant: dialog_NOCHOICE
  143.  
  144.   Purpose:  The setting returned by Dialog_LastClicked() when the user has
  145.             not yet done anything (i.e. no icons have been clicked and the
  146.             window is open)
  147.   SeeAlso:  Dialog_LastClicked
  148.  
  149. ****************************************************************************/
  150.  
  151.  
  152.  
  153. /*F*************************************************************************/
  154.  
  155.   extern dialog Dialog_Create(char *template_name, int maxtitlesize);
  156.  
  157. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  158.  
  159.   Inputs:   template_name - the name of the window template to use in
  160.                             constructing the dialog box.
  161.             maxtitlesize  - the maximum space to reserve for the dialog box
  162.                             title bar (See Window_Create for more details).
  163.   Returns:  dialog - the newly created dialog box, or NULL if it was not
  164.                      possible to create the dialog.
  165.   Purpose:  Creates (but does not show) a dialog box from a named template.
  166.   Errors:   Out of memory; Could not find window template
  167.   SeeAlso:  Window_Create; Dialog_Show; Dialog_ShowStatic
  168.  
  169. ****************************************************************************/
  170.  
  171.  
  172.  
  173. /*F*************************************************************************/
  174.  
  175.   extern void Dialog_Destroy(dialog d);
  176.  
  177. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  178.  
  179.   Inputs:   d - the dialog box to destroy.
  180.   Purpose:  Removes from display and deletes a dialog box structure.
  181.             NOTE that the dialog structure is free'd by this, so you cannot
  182.             call any dialog functions (except Create of course) with it
  183.             after a Destroy.
  184.   SeeAlso:  Dialog_Create; Dialog_Hide
  185.  
  186. ****************************************************************************/
  187.  
  188.  
  189.  
  190.  
  191. /*F*************************************************************************/
  192.  
  193.   extern void Dialog_Show(dialog d);
  194.  
  195. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  196.  
  197.   Inputs:   d - the dialog box to show.
  198.   Purpose:  Shows a dialog box in the centre of the screen, as a submenu
  199.             window. (i.e. clicking outside the window or pressing escape
  200.             will remove it)
  201.   SeeAlso:  Dialog_ShowAt; Dialog_ShowStatic
  202.  
  203. ****************************************************************************/
  204.  
  205.  
  206.  
  207. /*F*************************************************************************/
  208.  
  209.   extern void Dialog_ShowAt(dialog d, int x, int y);
  210.  
  211. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  212.  
  213.   Inputs:   d    - the dialog to show.
  214.             x, y - the position to show the window at (top-left of window
  215.                    area).
  216.   Purpose:  Shows a dialogue box at a specified position. (i.e. clicking
  217.             outside the window or pressing escape will remove it)
  218.   SeeAlso:  Dialog_Show; Dialog_ShowStatic
  219.  
  220. ****************************************************************************/
  221.  
  222.  
  223.  
  224.  
  225. /*F*************************************************************************/
  226.  
  227.   extern void Dialog_ShowStatic(dialog d, window_openpos openpos);
  228.  
  229. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  230.  
  231.   Inputs:   d - the dialog to show.
  232.             openpos - where to show the dialog.
  233.   Purpose:  As Dialog_Show(), but more permanent - only a click on the close
  234.             icon (if present) will close it.  Of course it may be closed by
  235.             other means if the application assigns special meaning to an
  236.             icon  - e.g. a cancel button - and closes it itself when this
  237.             icon is clicked on.
  238.             Opens the window at the position requested (see Window.h), of:
  239.               open_ WHEREVER, CENTERED, OVERCARET, UNDERPOINTER, NEARLAST
  240.  
  241.             (It is very convenient if dialogs always appear under the mouse
  242.             pointer especially as mouse-movement distances (screen sizes)
  243.             increase.)
  244.   SeeAlso:  Dialog_Show; Dialog_ShowAt
  245.  
  246. ****************************************************************************/
  247.  
  248.  
  249.  
  250. /*F*************************************************************************/
  251.  
  252.   extern void Dialog_Hide(dialog d);
  253.  
  254. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  255.  
  256.   Inputs:   d - the dialog to hide.
  257.   Purpose:  Hides the dialog box by closing the window, but does not
  258.             destroy it.
  259.             Subsequent calls to Dialog_Show[Static] will work correctly.
  260.   SeeAlso:  Dialog_Show; Dialog_Destroy
  261.  
  262. ****************************************************************************/
  263.  
  264.  
  265.  
  266. /*F*************************************************************************/
  267.  
  268.   extern int Dialog_WaitForClick(dialog d);
  269.  
  270. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  271.  
  272.   Inputs:   d - the dialog to process click events for.
  273.   Returns:  The handle of the icon clicked, or dialog_CLOSE.
  274.   Purpose:  Waits for an icon to be clicked in the dialogue box.  All other
  275.             events are processed as usual.  If the user closes the window,
  276.             dialog_CLOSE is returned.
  277.             Note that Dialog_LastClicked can be called at any time up until
  278.             you call Dialog_Destroy() to find out what the last valid icon
  279.             click was (i.e. the last positive value that Dialog_WaitForClick
  280.             returned)
  281.   SeeAlso:  Dialog_LastClicked
  282.  
  283. ****************************************************************************/
  284.  
  285.  
  286.  
  287. /*M*************************************************************************/
  288.  
  289.   #define Dialog_WindowHandle(d) ((d)->window)
  290.  
  291. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  292.  
  293.   MACRO:    window_handle Dialog_WindowHandle(dialog d)
  294.  
  295.   Inputs:   d - the dialog in question.
  296.   Returns:  Window handle of the dialog.
  297.   Purpose:  Obtain the RISC OS Wimp window handle associated with this
  298.             dialog box.  This allows filling in of fields using, e.g.
  299.             DeskLib's 'Icon' module.
  300.  
  301. ****************************************************************************/
  302.  
  303.  
  304.  
  305. /*M*************************************************************************/
  306.  
  307.   #define Dialog_Persist(D) ((D)->state.persist && (D)->lastclicked >= 0)
  308.  
  309. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  310.  
  311.   MACRO:    BOOL Dialog_Persist(dialog d);
  312.  
  313.   Inputs:   d - the dialog to be checked for persistence.
  314.   Returns:  TRUE if the last choice made on this dialog was made using
  315.             'adjust' - i.e. the user wants the dialog to stay open;
  316.             FALSE otherwise.
  317.   Purpose:  Find out if the user wants the dialog to stay open after a
  318.             click event.
  319.             Unlike RISC OS Lib, this remembers the last click rather than
  320.             just checking if Adjust is down when called, so will work even
  321.             after an indentation delay.
  322.   SeeAlso:  Dialog_LastClicked; Dialog_StillOpen
  323.  
  324. ****************************************************************************/
  325.  
  326.  
  327.  
  328. /*M*************************************************************************/
  329.  
  330.   #define Dialog_LastClicked(D) ((D)->lastclicked)
  331.  
  332. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  333.  
  334.   MACRO:    icon_handle Dialog_LastClicked(dialog d);
  335.  
  336.   Inputs:   d - the dialog to check for the click event.
  337.   Returns:  The handle of the icon that was last clicked on this dialog,
  338.             or dialog_NOCHOICE if the user has not yet clicked an icon.
  339.   Purpose:  find out the last icon clicked on by the user in this dialog.
  340.   SeeAlso:  Dialog_Persist; Dialog_StillOpen
  341.  
  342. ****************************************************************************/
  343.  
  344.  
  345.  
  346. /*M*************************************************************************/
  347.  
  348.   #define Dialog_StillOpen(D) ((D)->state.stillopen)
  349.  
  350. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  351.  
  352.   MACRO:    BOOL Dialog_StillOpen(dialog d)
  353.  
  354.   Inputs:   d - the dialog to check.
  355.   Returns:  TRUE if the dialog box is still open on screen;
  356.             FALSE otherwise.
  357.   Purpose:  Find out if a dialog box is still open or not.
  358.   SeeAlso:  Dialog_Persist; Dialog_LastClicked.
  359.  
  360. ****************************************************************************/
  361.  
  362.  
  363. #endif
  364.