home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / gui / precog2_1.lha / Precognition2_1 / NewDocs / utility_funcs.doc < prev   
Encoding:
Text File  |  1995-01-13  |  11.6 KB  |  292 lines
  1. Utility Functions available in precognition.lib:
  2.  
  3. Intuition_Utils.h
  4. ==================
  5. Runtime environment Version Checking Functions:
  6. -----------------------------------------------
  7. Name:    is_Workbench_v2 - returns TRUE if running AmigaDOS version >= 2.0
  8. Syntax:  | result = is_Workbench_v2();
  9.          | BOOL result;
  10.  
  11.  
  12. Name:    is_Workbench_v2_1 - returns TRUE if running AmigaDOS version >= 2.1
  13. Syntax:  | result = is_Workbench_v2_1();
  14.          | BOOL result;
  15.  
  16.  
  17. Name:    is_Workbench_v3 - returns TRUE if running AmigaDOS version >= 3.0
  18. Syntax:  | result = is_Workbench_v3();
  19.          | BOOL result;
  20.  
  21.  
  22. Name:    is_Workbench_v3_1 - returns TRUE if running AmigaDOS version >= 3.1
  23. Syntax:  | result = is_Workbench_v3_1();
  24.          | BOOL result;
  25.  
  26. Intuition Functions:
  27. ---------------------
  28. Name:          GadgetRelativeCoords - translates mouse coords relative to gadget
  29. Syntax:        | GadgetRelativeCoords( gadget, event, point );
  30.                | struct Gadget *gadget;
  31.                | struct IntuiMessage *event;
  32.                | Point *point;
  33.  
  34. Description:   'GadgetRelativeCoords()' is a function which translates
  35.                the MouseX and MouseY fields of an IntuiMessage to be
  36.                relative the supplied gadget.  (MouseX and MouseY are
  37.                returned by Intuition relative to the window, not the
  38.                gadget.)
  39.  
  40. Notes:         AmigaDOS version 2.0 intuition.library has
  41.                a built-in function to do this.
  42.  
  43.  
  44. Name:          SetWaitPointer - sets the pointer to the standard 2.0 'clock'.
  45. Syntax:        | SetWaitPointer( w );
  46.                | struct Window *w;
  47. Description:   'SetWaitPointer()' sets the mouse pointer to look like
  48.                the standard Workbench 2.0 wait pointer (a clock).
  49.  
  50.  
  51. Name:          WaitForMessage - waits for and returns an IntuiMessage.
  52. Syntax:        | imgs = WaitForMessage( mport );
  53.                | struct IntuiMessage *imsg;
  54.                | struct MsgPort *mport;
  55.  
  56. Description:   Most Intuition event loops start out with the
  57.                following statements to get a message:
  58.                |
  59.                | for(;;)
  60.                | {
  61.                |    msg = (struct IntuiMessage*) GetMsg( window->UserPort );
  62.                |    if (msg == NULL)
  63.                |    {
  64.                |       WaitPort(window->UserPort);
  65.                |       continue;
  66.                |    }
  67.                |
  68.                This grabs a message from the port, and if no message is there,
  69.                does a Wait, and tries again.  I always found this code
  70.                somewhat confusing and very ugly.  So I wrote WaitForMessage
  71.                to hide it.
  72.  
  73.                'WaitForMessage()' does not return until it finds a message,
  74.                so the above code can be replaced by:
  75.                |
  76.                | for(;;)
  77.                | {
  78.                |    msg = WaitForMessage( window->UserPort );
  79.                |
  80.  
  81.  
  82. Name:          OpenWindowWithSharedUserPort - opens a window with a shared port.
  83. Syntax:        | window = OpenWindowWithSharedPort( nw, port );
  84.                | struct Window    *window;
  85.                | struct NewWindow *nw;
  86.                | struct MsgPort   *port;
  87.  
  88. Description:   To handle multiple windows within the one application, the
  89.                best method (usually) is to have all the windows share the
  90.                same UserPort.  This way, one can still do a 'WaitPort()' or
  91.                'WaitForMessage()'.  (Otherwise one has to mess with signal
  92.                bits.)
  93.  
  94.                In order to force a window to have a specific UserPort, one
  95.                must first create the port (using 'CreatePort()'), and then
  96.                there is a sequence of steps involved in opening the window.
  97.                (This is described in the 1.3 RKM Libraries and Devices manual
  98.                on page 167 "SETTING UP YOUR OWN IDCMP MONITOR TASK AND USER
  99.                PORT")
  100.  
  101.                'OpenWindowWithSharedPort()' does all the steps after the
  102.                creation of the MsgPort.   All you do is pass in the NewWindow
  103.                structure and the message port, and
  104.                'OpenWindowWithSharedUserPort' will open the window and do
  105.                the UserPort setup.
  106.  
  107. Note:          Windows opened with this function must be closed using
  108.                'CloseWindowWithSharedUserPort()', NOT 'CloseWindow()'!
  109.  
  110. See Also:      CloseWindowWithSharedUserPort
  111.  
  112.  
  113. Name:          CloseWindowWithSharedUserPort - closes a window with a shared port.
  114. Syntax:        | CloseWindowWithSharedPort( w );
  115.                | struct Window *w;
  116. Description:   To handle multiple windows within the one application, the
  117.                best method (usually) is to have all the windows share the
  118.                same UserPort.  This way, one still to a 'WaitPort()' or
  119.                'WaitForMessage()'.  (Otherwise one has to mess with signal
  120.                bits.)
  121.  
  122.                Closing such a window requires some care, as Intuition normally
  123.                deallocates the UserPort for such a window on closing, and
  124.                since the port is shared, other windows are still using it!
  125.                (This is described in the 1.3 RKM Libraries and Devices manual
  126.                on page 167 "SETTING UP YOUR OWN IDCMP MONITOR TASK AND USER
  127.                PORT")
  128.  
  129.                'CloseWindowWithSharedUserPort()' does all this for you.
  130.  
  131. See Also:      OpenWindowWithSharedUserPort
  132.  
  133.  
  134. Name:          WindowSanityCheck - checks the size and location of a window
  135. Syntax:        | ok = WindowSanityCheck( screen, location, size );
  136.                | BOOL ok;
  137.                | struct Screen *screen;
  138.                | Point *location;
  139.                | Point *size;
  140.  
  141. Description:   WindowSanityCheck checks a proposed new size and location
  142.                for a window to make sure those dimensions will not exceed
  143.                the screen size.
  144.  
  145.                WindowSanityCheck returns TRUE if the proposed dimensions
  146.                are ok, and FALSE if the window dimensions must be changed.
  147.                If the return is FALSE, the values of 'location' and 'size'
  148.                are returned modified to the closest legal dimensions.
  149.  
  150.  
  151. Name:          SmartOpenScreen - Opens a screen in WB2.0 style if appropriate.
  152. Syntax:        | screen = SmartOpenScreen( newscreen );
  153.                | struct Screen *screen;
  154.                | struct NewScreen *newscreen;
  155.  
  156. Description:   SmartOpenScreen opens a screen.  If you're running under
  157.                1.3, it just calls OpenScreen.  If you're running under
  158.                2.0, it does the minimal processing required so that windows
  159.                on the screen get the 3D look.
  160.  
  161. Name:          SmartOpenScreen - Opens a screen in WB3.0 style if appropriate.
  162. Syntax:        | window = SmartOpenWindow( newwindow );
  163.                | struct Window *window;
  164.                | struct NewWindow *newwindow;
  165.  
  166. Description:   SmartOpenWindow opens a window.  If you're running under
  167.                1.3, it just calls OpenWindow.  If you're running under
  168.                3.0, it does the minimal processing required so that menus
  169.                under 3.0 Amiga OS get the new black text on white background
  170.                look. This also requires a change to the menu code as well.
  171.  
  172.  
  173. Name:          RemapImage() - flips planes 1&2 of an image
  174. Syntax:        | RemapImage( image );
  175.                | struct Image *image;
  176.  
  177. Description:   RemapImage exchanges the first two planes of an image data
  178.                structure.  This converts from the look of Workbench 1.2/3
  179.                to the look of Workbench 2.0.
  180.  
  181.                It ASSUMES that there are two planes (i.e. don't feed
  182.                it PlanePick'ed images.)
  183.  
  184.  
  185. Precognition_Utils.h
  186. ====================
  187. Name:         pcg_GadgetRelativeCoords( gadget, event )
  188. Syntax:
  189.  
  190. Description:  macro for GadgetRelativeCoords(g,e)
  191.               Translates the MouseX, MouseY coordinates of a gadget-related
  192.               IntuiMessage into coordinates which are relative to the gadget
  193.               instead of the window.
  194.  
  195.  
  196. Name:         ChainGadgets( start_of_chain, gadget )
  197. Syntax:       |  void ChainGadgets( start_of_chain, gadget );
  198.               |  struct Gadget *start_of_chain;
  199.               |  struct Gadget *gadget;
  200.  
  201. Description:  Adds 'gadget' to chain (list) of gadgets pointed to by 'start_of_chain'
  202.  
  203.  
  204. Name:         AlignText( ptext, size )
  205. Syntax:       |  void AlignText( ptext, size )
  206.               |  struct PrecogText *ptext;
  207.               |  Point size;
  208.  
  209. Description:  Aligns text 'ptext' relative to an object of dimensions 'size'
  210.  
  211.  
  212. Name:         pcgTextSize( ptext );
  213. Syntax:       |  void pcgTextSize( ptext );
  214.               |  struct PrecogText *ptext;
  215.  
  216. Description:  Sets the PrecogText TextLength field by using IntuiTextLength()
  217.               function on the text string with the given font attributes.
  218.  
  219. Precognition3D.h
  220. ====================
  221. Name:         StandardPens()
  222. Syntax:       mypens = StandardPens();
  223.               | struct pcg_3DPens *mypens;
  224.  
  225. Description:  Returns the standard color pens (4) for Workbench 1.3 or 2.0 and above
  226.  
  227.  
  228. Name:         StandardScreenPens( screen )
  229. Syntax:       mypens = StandardScreenPens( screen );
  230.               | struct pcg_3DPens *mypens;
  231.               | struct Screen *screen;
  232.  
  233. Description:  Returns the standard color pens. depending on depth of whichscreen.
  234.               If whichscreen == NULL, Workbench is presumed for Amiga OS 1.3 and
  235.               the default public screen is presumed for Amiga OS 2.x and above.
  236.               Monochrome screens get a proper 2D style look and screens with
  237.               Depths of 2 and greater are accomodated with proper pens for 3D style.
  238.  
  239.  
  240. Name:         pcg_Init3DBox( Box, LeftEdge, TopEdge, Width, Height, TopLeftPen, BottomRightPen, NextBorder )
  241. Syntax:       void pcg_Init3DBox( Box, LeftEdge, TopEdge, Width, Height, TopLeftPen, BottomRightPen, NextBorder )
  242.               | pcg_3DBox *Box;
  243.               | SHORT      LeftEdge;
  244.               | SHORT      TopEdge;
  245.               | USHORT     Width;
  246.               | USHORT     Height;
  247.               | UBYTE      TopLeftPen;
  248.               | UBYTE      BottomRightPen;
  249.               | Border    *NextBorder;
  250.  
  251. Description:
  252.  
  253. Name:         pcg_Init3DBevel( Bevel, LeftEdge, TopEdge, Width, Height, BevelWidth, TopLeftPen, BottomRightPen, NextBorder )
  254. Syntax:       void  pcg_Init3DBevel( Bevel, LeftEdge, TopEdge, Width, Height, BevelWidth, TopLeftPen, BottomRightPen, NextBorder )
  255.               | pcg_3DBevel *Bevel;
  256.               | SHORT        LeftEdge;
  257.               | SHORT        TopEdge;
  258.               | USHORT       Width;
  259.               | USHORT       Height;
  260.               | USHORT       BevelWidth;
  261.               | UBYTE        TopLeftPen;
  262.               | UBYTE        BottomRightPen;
  263.               | Border      *NextBorder;
  264.  
  265. Description: LeftEdge, TopEdge, Width, Height refer to the _outer_ box.
  266.  
  267.              'BevelWidth' is the amount of blankspace between the inner and
  268.              outer border.  (0 is an ok value.)
  269.  
  270.              If 'TopLeftPen' is bright, and 'BottomRightPen' is dark, the bevel
  271.              will appear to stand out.  If 'TopLeftPen' is dark, the bevel will
  272.              appear recessed.
  273.  
  274.  
  275. Name:         pcg_Init3DThinBevel( Bevel, LeftEdge, TopEdge, Width, Height, BevelWidth, TopLeftPen, BottomRightPen, NextBorder )
  276.  
  277. Syntax:       void pcg_Init3DThinBevel( Bevel, LeftEdge, TopEdge, Width, Height, BevelWidth, TopLeftPen, BottomRightPen, NextBorder );
  278.               | pcg_3DThinBevel *Bevel;
  279.               | SHORT            LeftEdge;
  280.               | SHORT            TopEdge;
  281.               | USHORT           Width;
  282.               | USHORT           Height;
  283.               | USHORT           BevelWidth;
  284.               | UBYTE            TopLeftPen;
  285.               | UBYTE            BottomRightPen;
  286.               | Border          *NextBorder;
  287.  
  288.  
  289. Description:
  290.  
  291.  
  292.