Utility Functions available in precognition.lib: Intuition_Utils.h ================== Runtime environment Version Checking Functions: ----------------------------------------------- Name: is_Workbench_v2 - returns TRUE if running AmigaDOS version >= 2.0 Syntax: | result = is_Workbench_v2(); | BOOL result; Name: is_Workbench_v2_1 - returns TRUE if running AmigaDOS version >= 2.1 Syntax: | result = is_Workbench_v2_1(); | BOOL result; Name: is_Workbench_v3 - returns TRUE if running AmigaDOS version >= 3.0 Syntax: | result = is_Workbench_v3(); | BOOL result; Name: is_Workbench_v3_1 - returns TRUE if running AmigaDOS version >= 3.1 Syntax: | result = is_Workbench_v3_1(); | BOOL result; Intuition Functions: --------------------- Name: GadgetRelativeCoords - translates mouse coords relative to gadget Syntax: | GadgetRelativeCoords( gadget, event, point ); | struct Gadget *gadget; | struct IntuiMessage *event; | Point *point; Description: 'GadgetRelativeCoords()' is a function which translates the MouseX and MouseY fields of an IntuiMessage to be relative the supplied gadget. (MouseX and MouseY are returned by Intuition relative to the window, not the gadget.) Notes: AmigaDOS version 2.0 intuition.library has a built-in function to do this. Name: SetWaitPointer - sets the pointer to the standard 2.0 'clock'. Syntax: | SetWaitPointer( w ); | struct Window *w; Description: 'SetWaitPointer()' sets the mouse pointer to look like the standard Workbench 2.0 wait pointer (a clock). Name: WaitForMessage - waits for and returns an IntuiMessage. Syntax: | imgs = WaitForMessage( mport ); | struct IntuiMessage *imsg; | struct MsgPort *mport; Description: Most Intuition event loops start out with the following statements to get a message: | | for(;;) | { | msg = (struct IntuiMessage*) GetMsg( window->UserPort ); | if (msg == NULL) | { | WaitPort(window->UserPort); | continue; | } | This grabs a message from the port, and if no message is there, does a Wait, and tries again. I always found this code somewhat confusing and very ugly. So I wrote WaitForMessage to hide it. 'WaitForMessage()' does not return until it finds a message, so the above code can be replaced by: | | for(;;) | { | msg = WaitForMessage( window->UserPort ); | Name: OpenWindowWithSharedUserPort - opens a window with a shared port. Syntax: | window = OpenWindowWithSharedPort( nw, port ); | struct Window *window; | struct NewWindow *nw; | struct MsgPort *port; Description: To handle multiple windows within the one application, the best method (usually) is to have all the windows share the same UserPort. This way, one can still do a 'WaitPort()' or 'WaitForMessage()'. (Otherwise one has to mess with signal bits.) In order to force a window to have a specific UserPort, one must first create the port (using 'CreatePort()'), and then there is a sequence of steps involved in opening the window. (This is described in the 1.3 RKM Libraries and Devices manual on page 167 "SETTING UP YOUR OWN IDCMP MONITOR TASK AND USER PORT") 'OpenWindowWithSharedPort()' does all the steps after the creation of the MsgPort. All you do is pass in the NewWindow structure and the message port, and 'OpenWindowWithSharedUserPort' will open the window and do the UserPort setup. Note: Windows opened with this function must be closed using 'CloseWindowWithSharedUserPort()', NOT 'CloseWindow()'! See Also: CloseWindowWithSharedUserPort Name: CloseWindowWithSharedUserPort - closes a window with a shared port. Syntax: | CloseWindowWithSharedPort( w ); | struct Window *w; Description: To handle multiple windows within the one application, the best method (usually) is to have all the windows share the same UserPort. This way, one still to a 'WaitPort()' or 'WaitForMessage()'. (Otherwise one has to mess with signal bits.) Closing such a window requires some care, as Intuition normally deallocates the UserPort for such a window on closing, and since the port is shared, other windows are still using it! (This is described in the 1.3 RKM Libraries and Devices manual on page 167 "SETTING UP YOUR OWN IDCMP MONITOR TASK AND USER PORT") 'CloseWindowWithSharedUserPort()' does all this for you. See Also: OpenWindowWithSharedUserPort Name: WindowSanityCheck - checks the size and location of a window Syntax: | ok = WindowSanityCheck( screen, location, size ); | BOOL ok; | struct Screen *screen; | Point *location; | Point *size; Description: WindowSanityCheck checks a proposed new size and location for a window to make sure those dimensions will not exceed the screen size. WindowSanityCheck returns TRUE if the proposed dimensions are ok, and FALSE if the window dimensions must be changed. If the return is FALSE, the values of 'location' and 'size' are returned modified to the closest legal dimensions. Name: SmartOpenScreen - Opens a screen in WB2.0 style if appropriate. Syntax: | screen = SmartOpenScreen( newscreen ); | struct Screen *screen; | struct NewScreen *newscreen; Description: SmartOpenScreen opens a screen. If you're running under 1.3, it just calls OpenScreen. If you're running under 2.0, it does the minimal processing required so that windows on the screen get the 3D look. Name: SmartOpenScreen - Opens a screen in WB3.0 style if appropriate. Syntax: | window = SmartOpenWindow( newwindow ); | struct Window *window; | struct NewWindow *newwindow; Description: SmartOpenWindow opens a window. If you're running under 1.3, it just calls OpenWindow. If you're running under 3.0, it does the minimal processing required so that menus under 3.0 Amiga OS get the new black text on white background look. This also requires a change to the menu code as well. Name: RemapImage() - flips planes 1&2 of an image Syntax: | RemapImage( image ); | struct Image *image; Description: RemapImage exchanges the first two planes of an image data structure. This converts from the look of Workbench 1.2/3 to the look of Workbench 2.0. It ASSUMES that there are two planes (i.e. don't feed it PlanePick'ed images.) Precognition_Utils.h ==================== Name: pcg_GadgetRelativeCoords( gadget, event ) Syntax: Description: macro for GadgetRelativeCoords(g,e) Translates the MouseX, MouseY coordinates of a gadget-related IntuiMessage into coordinates which are relative to the gadget instead of the window. Name: ChainGadgets( start_of_chain, gadget ) Syntax: | void ChainGadgets( start_of_chain, gadget ); | struct Gadget *start_of_chain; | struct Gadget *gadget; Description: Adds 'gadget' to chain (list) of gadgets pointed to by 'start_of_chain' Name: AlignText( ptext, size ) Syntax: | void AlignText( ptext, size ) | struct PrecogText *ptext; | Point size; Description: Aligns text 'ptext' relative to an object of dimensions 'size' Name: pcgTextSize( ptext ); Syntax: | void pcgTextSize( ptext ); | struct PrecogText *ptext; Description: Sets the PrecogText TextLength field by using IntuiTextLength() function on the text string with the given font attributes. Precognition3D.h ==================== Name: StandardPens() Syntax: mypens = StandardPens(); | struct pcg_3DPens *mypens; Description: Returns the standard color pens (4) for Workbench 1.3 or 2.0 and above Name: StandardScreenPens( screen ) Syntax: mypens = StandardScreenPens( screen ); | struct pcg_3DPens *mypens; | struct Screen *screen; Description: Returns the standard color pens. depending on depth of whichscreen. If whichscreen == NULL, Workbench is presumed for Amiga OS 1.3 and the default public screen is presumed for Amiga OS 2.x and above. Monochrome screens get a proper 2D style look and screens with Depths of 2 and greater are accomodated with proper pens for 3D style. Name: pcg_Init3DBox( Box, LeftEdge, TopEdge, Width, Height, TopLeftPen, BottomRightPen, NextBorder ) Syntax: void pcg_Init3DBox( Box, LeftEdge, TopEdge, Width, Height, TopLeftPen, BottomRightPen, NextBorder ) | pcg_3DBox *Box; | SHORT LeftEdge; | SHORT TopEdge; | USHORT Width; | USHORT Height; | UBYTE TopLeftPen; | UBYTE BottomRightPen; | Border *NextBorder; Description: Name: pcg_Init3DBevel( Bevel, LeftEdge, TopEdge, Width, Height, BevelWidth, TopLeftPen, BottomRightPen, NextBorder ) Syntax: void pcg_Init3DBevel( Bevel, LeftEdge, TopEdge, Width, Height, BevelWidth, TopLeftPen, BottomRightPen, NextBorder ) | pcg_3DBevel *Bevel; | SHORT LeftEdge; | SHORT TopEdge; | USHORT Width; | USHORT Height; | USHORT BevelWidth; | UBYTE TopLeftPen; | UBYTE BottomRightPen; | Border *NextBorder; Description: LeftEdge, TopEdge, Width, Height refer to the _outer_ box. 'BevelWidth' is the amount of blankspace between the inner and outer border. (0 is an ok value.) If 'TopLeftPen' is bright, and 'BottomRightPen' is dark, the bevel will appear to stand out. If 'TopLeftPen' is dark, the bevel will appear recessed. Name: pcg_Init3DThinBevel( Bevel, LeftEdge, TopEdge, Width, Height, BevelWidth, TopLeftPen, BottomRightPen, NextBorder ) Syntax: void pcg_Init3DThinBevel( Bevel, LeftEdge, TopEdge, Width, Height, BevelWidth, TopLeftPen, BottomRightPen, NextBorder ); | pcg_3DThinBevel *Bevel; | SHORT LeftEdge; | SHORT TopEdge; | USHORT Width; | USHORT Height; | USHORT BevelWidth; | UBYTE TopLeftPen; | UBYTE BottomRightPen; | Border *NextBorder; Description: