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