home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 3 / CDPDIII.bin / pd / programming / utils / precognition / include / intuition_utils.h < prev    next >
Encoding:
C/C++ Source or Header  |  1992-12-23  |  9.5 KB  |  292 lines
  1. #ifndef INTUITION_UTILS_H
  2. #define INTUITION_UTILS_H
  3.  
  4. #include <exec/types.h>
  5. #include <intuition/intuition.h>
  6. #include <intuition/screens.h>
  7. #include <graphics/gfx.h>        /* for type 'Point' */
  8.  
  9. /* ~~~~~~~~~~~~~~~~~~~ Intuition_Utils ~~~~~~~~~~~~~~~~~~~~~~~~~~
  10.  
  11.    This is a collection of handy Intuition-related utilities.
  12.    These do not depend on any of the Precognition types or routines
  13.    and can be reused outside of the Precognition environment.
  14.  
  15.    Note: the strange comment headers are for use with a tool
  16.    which automatically builds man pages from the comments.
  17. */
  18.  
  19.  
  20. /*F:is_Workbench_v2*
  21.  
  22. ----------------------------------------------------
  23.  
  24.          is_Workbench_v2
  25.  
  26. ----------------------------------------------------
  27.  
  28. Name:    is_Workbench_v2 - returns TRUE if running AmigaDOS version >= 2.0
  29. Syntax:  | result = is_Workbench_v2();
  30.          | BOOL result;
  31. Author:  Lee R. Willis
  32. */
  33.  
  34. BOOL is_Workbench_v2( void );
  35.  
  36.  
  37.  
  38. /*F:GadgetRelativeCoords*
  39.  
  40. ----------------------------------------------------
  41.  
  42.                GadgetRelativeCoords
  43.  
  44. ----------------------------------------------------
  45.  
  46. Name:          GadgetRelativeCoords - translates mouse coords relative to gadget
  47. Syntax:        | GadgetRelativeCoords( gadget, event, point );
  48.                | struct Gadget *gadget;
  49.                | struct IntuiMessage *event;
  50.                | Point *point;
  51. Description:   'GadgetRelativeCoords()' is a function which translates
  52.                the MouseX and MouseY fields of an IntuiMessage to be
  53.                relative the supplied gadget.  (MouseX and MouseY are
  54.                returned by Intuition relative to the window, not the
  55.                gadget.)
  56.  
  57. Notes:         AmigaDOS version 2.0 intuition.library has
  58.                a built-in function to do this.
  59.  
  60. Author:  Lee R. Willis
  61. */
  62.  
  63. void GadgetRelativeCoords( struct Gadget       *gadget,
  64.                            struct IntuiMessage *event,
  65.                            Point               *point );
  66.  
  67.  
  68.  
  69. /*F:SetWaitPointer*
  70.  
  71. -------------------------------------------------
  72.  
  73.                SetWaitPointer
  74.  
  75. -------------------------------------------------
  76.  
  77. Name:          SetWaitPointer - sets the pointer to the standard 2.0 'clock'.
  78. Syntax:        | SetWaitPointer( w );
  79.                | struct Window *w;
  80. Description:   'SetWaitPointer()' sets the mouse pointer to look like
  81.                the standard Workbench 2.0 wait pointer (a clock).
  82. Author:        Lee R. Willis
  83. */
  84.  
  85. void SetWaitPointer( struct Window *w );
  86.  
  87.  
  88. /*F:WaitForMessage
  89.  
  90. ----------------------------------------------------
  91.  
  92.                WaitForMessage
  93.  
  94. ----------------------------------------------------
  95.  
  96. Name:          WaitForMessage - waits for and returns an IntuiMessage.
  97. Syntax:        | imgs = WaitForMessage( mport );
  98.                | struct IntuiMessage *imsg;
  99.                | struct MsgPort *mport;
  100.  
  101. Description:   Most Intuition event loops start out with the
  102.                following statements to get a message:
  103.                |
  104.                | for(;;)
  105.                | {
  106.                |    msg = (struct IntuiMessage*) GetMsg( window->UserPort );
  107.                |    if (msg == NULL)
  108.                |    {
  109.                |       WaitPort(window->UserPort);
  110.                |       continue;
  111.                |    }
  112.                |
  113.                This grabs a message from the port, and if no message is there,
  114.                does a Wait, and tries again.  I always found this code
  115.                somewhat confusing and very ugly.  So I wrote WaitForMessage
  116.                to hide it.
  117.  
  118.                'WaitForMessage()' does not return until it finds a message,
  119.                so the above code can be replaced by:
  120.                |
  121.                | for(;;)
  122.                | {
  123.                |    msg = WaitForMessage( window->UserPort );
  124.                |
  125.  
  126. Author:        Lee R. Willis
  127. */
  128.  
  129.  
  130. struct IntuiMessage *WaitForMessage( struct MsgPort *mport );
  131.  
  132.  
  133. /*F:OpenWindowWithSharedUserPort*
  134.  
  135. ------------------------------------------------------------
  136.  
  137.                OpenWindowWithSharedUserPort
  138.  
  139. ------------------------------------------------------------
  140.  
  141. Name:          OpenWindowWithSharedUserPort - opens a window with a shared port.
  142. Syntax:        | window = OpenWindowWithSharedPort( nw, port );
  143.                | struct Window    *window;
  144.                | struct NewWindow *nw;
  145.                | struct MsgPort   *port;
  146.  
  147. Description:   To handle multiple windows within the one application, the
  148.                best method (usually) is to have all the windows share the
  149.                same UserPort.  This way, one can still do a 'WaitPort()' or
  150.                'WaitForMessage()'.  (Otherwise one has to mess with signal
  151.                bits.)
  152.  
  153.                In order to force a window to have a specific UserPort, one
  154.                must first create the port (using 'CreatePort()'), and then
  155.                there is a sequence of steps involved in opening the window.
  156.                (This is described in the 1.3 RKM Libraries and Devices manual
  157.                on page 167 "SETTING UP YOUR OWN IDCMP MONITOR TASK AND USER
  158.                PORT")
  159.  
  160.                'OpenWindowWithSharedPort()' does all the steps after the
  161.                creation of the MsgPort.   All you do is pass in the NewWindow
  162.                structure and the message port, and
  163.                'OpenWindowWithSharedUserPort' will open the window and do
  164.                the UserPort setup.
  165.  
  166. Note:          Windows opened with this function must be closed using
  167.                'CloseWindowWithSharedUserPort()', NOT 'CloseWindow()'!
  168.  
  169. See Also:      CloseWindowWithSharedUserPort
  170. Author:        Lee R. Willis
  171. */
  172.  
  173. struct Window *OpenWindowWithSharedUserPort( struct NewWindow *nw,
  174.                                              struct MsgPort   *shared );
  175.  
  176.  
  177. /*F:CloseWindowWithSharedUserPort*
  178.  
  179. ------------------------------------------------------------
  180.  
  181.                CloseWindowWithSharedUserPort
  182.  
  183. ------------------------------------------------------------
  184.  
  185. Name:          CloseWindowWithSharedUserPort - closes a window with a shared port.
  186. Syntax:        | CloseWindowWithSharedPort( w );
  187.                | struct Window *w;
  188. Description:   To handle multiple windows within the one application, the
  189.                best method (usually) is to have all the windows share the
  190.                same UserPort.  This way, one still to a 'WaitPort()' or
  191.                'WaitForMessage()'.  (Otherwise one has to mess with signal
  192.                bits.)
  193.  
  194.                Closing such a window requires some care, as Intuition normally
  195.                deallocates the UserPort for such a window on closing, and
  196.                since the port is shared, other windows are still using it!
  197.                (This is described in the 1.3 RKM Libraries and Devices manual
  198.                on page 167 "SETTING UP YOUR OWN IDCMP MONITOR TASK AND USER
  199.                PORT")
  200.  
  201.                'CloseWindowWithSharedUserPort()' does all this for you.
  202.  
  203. See Also:      OpenWindowWithSharedUserPort
  204. Author:        Lee R. Willis
  205. */
  206.  
  207. void CloseWindowWithSharedUserPort( struct Window *w );
  208.    /* Taken from 1.3 RKM:L&D, page 171 'CloseWindowSafely' */
  209.  
  210.  
  211. /*F:WindowSanityCheck
  212.  
  213. ------------------------------------------------------------
  214.  
  215.                WindowSanityCheck
  216.  
  217. ------------------------------------------------------------
  218.  
  219. Name:          WindowSanityCheck - checks the size and location of a window
  220. Syntax:        | ok = WindowSanityCheck( screen, location, size );
  221.                | BOOL ok;
  222.                | struct Screen *screen;
  223.                | Point *location;
  224.                | Point *size;
  225.  
  226. Description:   WindowSanityCheck checks a proposed new size and location
  227.                for a window to make sure those dimensions will not exceed
  228.                the screen size.
  229.  
  230.                WindowSanityCheck returns TRUE if the proposed dimensions
  231.                are ok, and FALSE if the window dimensions must be changed.
  232.                If the return is FALSE, the values of 'location' and 'size'
  233.                are returned modified to the closest legal dimensions.
  234.  
  235. Author:        Lee R. Willis
  236. */
  237.  
  238. BOOL WindowSanityCheck( struct Screen *screen,
  239.                         Point         *location,
  240.                         Point         *size );
  241.  
  242.  
  243. /*F:SmartOpenScreen
  244.  
  245. -----------------------------------------------------------------
  246.  
  247.                SmartOpenScreen
  248.  
  249. -----------------------------------------------------------------
  250.  
  251. Name:          SmartOpenScreen - Opens a screen in WB2.0 style if appropriate.
  252. Syntax:        | screen = SmartOpenScreen( newscreen );
  253.                | struct Screen *screen;
  254.                | struct NewScreen *newscreen;
  255.  
  256. Description:   SmartOpenScreen opens a screen.  If you're running under
  257.                1.3, it just calls OpenScreen.  If you're running under
  258.                2.0, it does the minimal processing required so that windows
  259.                on the screen get the 3D look.
  260.  
  261. Author:        Lee R Willis
  262. */
  263.  
  264. struct Screen *SmartOpenScreen( struct NewScreen *newscreen );
  265.  
  266.  
  267.  
  268. /*F:RemapImage
  269.  
  270. ------------------------------------------------------------------
  271.  
  272.       RemapImage
  273.  
  274. ------------------------------------------------------------------
  275.  
  276. Name:          RemapImage() - flips planes 1&2 of an image
  277. Syntax:        | RemapImage( image );
  278.                | struct Image *image;
  279.  
  280. Description:   RemapImage exchanges the first two planes of an image data
  281.                structure.  This converts from the look of Workbench 1.2/3
  282.                to the look of Workbench 2.0.
  283.  
  284.                It ASSUMES that there are two planes (i.e. don't feed
  285.                it PlanePick'ed images.)
  286.  
  287. Author:        Lee R Willis
  288. */
  289. void RemapImage( struct Image *image );
  290.  
  291. #endif
  292.