(******************************************************************************)
(*                                                                            *)
(*    The global constants and variables defined in this module are optional: *)
(* if you don't want to access their features, you needn't import them into   *)
(* your program. The variables in the parameter lists of the procedures are   *)
(* the only variables you are required to supply.                             *)
(*    When describing the order in which certain routines are called, I have  *)
(* adopted the curly-bracket notation of EBNF: routines in curly brackets {}  *)
(* may be called an arbitrary number of times (0 to n). A, {B}, {C, {D}} thus *)
(* implies that A is called once, followed by an arbitrary number of calls to *)
(* to B, followed by an arbitrary number of calls to C. Each of the calls to  *)
(* C may be followed by an arbitrary number of calls to D. Likewise, {{C},{D}}*)
(* implies an arbitrary number of calls to C and D in any order.              *)
(*                                                                            *)
(******************************************************************************)
(*                                                                            *)
(*  Version 1.00a.002 (Beta) :   March 2, 1988                                *)
(*                                                                            *)
(*    These procedures were originally written under version 1.20 of the TDI  *)
(* Modula-2 compiler. I have rewritten this module to operate under the v2.00 *)
(* compiler. However, should you find any problem or inconsistency with the   *)
(* functionality of this code, please contact me at the following address:    *)
(*                                                                            *)
(*                               Jerry Mack                                   *)
(*                               23 Prospect Hill Ave.                        *)
(*                               Waltham, MA   02154                          *)
(*                                                                            *)
(*    Check the module MenuUtils for TDI's (considerably less powerful) ver-  *)
(* sions of my Menu and IntuitionText procedures. The modules GadgetUtils and *)
(* EasyGadgets should also be of great help.                                  *)
(*                                                                            *)
(******************************************************************************)
(*                                                                            *)
(*    The source code to WindowTools is in the public domain. You may do with *)
(* it as you please.                                                          *)
(*                                                                            *)
(******************************************************************************)

DEFINITION MODULE WindowTools;

FROM GraphicsBase    IMPORT GfxBasePtr;
FROM GraphicsLibrary IMPORT BitMapPtr;
FROM Intuition       IMPORT ScreenPtr, ScreenFlagSet, WindowPtr, WindowFlagSet,
                            IDCMPFlagSet, IntuitionBasePtr;
FROM Strings         IMPORT String;
FROM Views           IMPORT ModeSet;


CONST
   NoTitle = 0C;                      (* no title for screen and/or window *)

VAR
   ViewFeatures    : ModeSet;         (* ViewPort type and capabilities    *)
   ScreenBitMap    : BitMapPtr;       (* custom Screen bitmap, if desired  *)
   ScreenFeatures  : ScreenFlagSet;   (* Screen type and capabilities      *)
   TextPen         : INTEGER;         (* color of text drawn in Screen     *)
   FillPen         : INTEGER;         (* color of background in Screen     *)
   MinWindowWide   : INTEGER;         (* minimum width  of next Window     *)
   MaxWindowWide   : INTEGER;         (* maximum width  of next Window     *)
   MinWindowHigh   : INTEGER;         (* minimum height of next Window     *)
   MaxWindowHigh   : INTEGER;         (* maximum height of next Windwo     *)
   WindowBitMap    : BitMapPtr;       (* custom Window bitmap, if desired  *)
   WindowFeatures  : WindowFlagSet;   (* Window type and capabilities      *)
   IDCMPFeatures   : IDCMPFlagSet;    (* types of Intuition messages wanted*)
   UserIntuiBase   : IntuitionBasePtr;(* address of IntuitionBase          *)
   UserGraphBase   : GfxBasePtr;      (* address of GraphicsBase           *)


   PROCEDURE OpenGraphics () : BOOLEAN;

   PROCEDURE CreateScreen (Left, Top, Wide, High : INTEGER;   (* Input *)
                           Bitplanes             : INTEGER;   (* Input *)
                           VAR ScreenTitle       : String)    : ScreenPtr;
   
   PROCEDURE CreateWindow (Left, Top, Wide, High : INTEGER;   (* Input *)
                           VAR WindowTitle       : String;    (* Input *)
                           UserScreen            : ScreenPtr) : WindowPtr;
                         
   PROCEDURE CloseGraphics ();


          (* Variables reset in PROCEDURE OpenGraphics (): *)

(*  TextPen = 0  MinWindowWide = 30  MinWindowHigh = 20  ScreenBitMap = NULL *)
(*  FillPen = 1  MaxWindowWide =  0  MaxWindowHigh =  0  WindowBitMap = NULL *)
(*  ViewFeatures   = Empty                                                   *)
(*  ScreenFeatures = CustomScreen                                            *)
(*  IDCMPFeatures  = MenuPick, CloseWindowFlag, NewSize, GadgetUp            *)
(*  WindowFeatures = SmartRefresh, WindowSizing, WindowDrag, WindowDepth,    *)
(*                   Activate, ReportMouseFlag                               *)
 
(* OpenGraphics may return a value of FALSE if either the IntuitionLibrary   *)
(* or the GraphicsLibrary could not be opened. Whichever of UserIntuiBase or *)
(* UserGraphBase = NULL is the library which could not be opened. You needn't*)
(* call CloseGraphics in such a case.                                        *) 

(* Both CreateScreen and CreateWindow do extensive checking to ensure that   *)
(* you don't exceed the performance limits of the Amiga. (I am FED UP with   *)
(* crashes!!) If you find any combination which doesn't work properly, I     *)
(* would appreciate your dropping me a line describing the invocation. Also, *)
(* Left and Top are measured from the upper-left corner of the display in    *)
(* CreateScreen, whereas in CreateWindow they are measured from the upper-   *)
(* left corner of the Screen in which the Window will appear.                *) 

(* If UserScreen = NULL, then the Window will open in the WorkBench Screen;  *)
(* otherwise, it will open in the UserScreen.                                *) 

(* ScreenBitMap and WindowBitMap are pointers to custom bitmaps. Unless you  *)
(* want to manage your own bitmaps, you should leave these alone (= NULL).   *)
 
(* TextPen and FillPen are chosen from the color palette; the number of pens *)
(* available = 2**bitplanes { or 2^bitplanes }. Any pen choice outside of    *)
(* this range results in choice wraparound, which I assume is done by ignor- *)
(* ing illegal higher-order bits.                                            *)
 
(* ViewFeatures determines the type of ViewPort in which you wish your Screen*)
(* to be rendered. Setting this to the appropriate value allows you to obtain*)
(* high-resolution, interlaced, HAM, ExtraHalfBright, etc. ViewPorts.        *)

(* ScreenFeatures determines how the Screen will appear in the display and   *)
(* whether or not the new Screen will be a CustomScreen.                     *)

(* WindowFeatures determines how the Window will appear in the display,what  *)
(* type of Gadgets you wish attached to it and how it will be refreshed.     *)

(* MinWindowWide, MaxWindowWide, MinWindowHigh and MaxWindowHigh are only of *)
(* use if the Window has a sizing gadget: INCL(WindowFeatures, WindowSizing).*) 
(* If any of these is set to 0, then the limit of that dimension will be the *)
(* current dimension of the Window.                                          *)
 
(* IDCMPFeatures determines which messages your Window will receive from In- *)
(* tuition. If your program isn't responding to certain gadgets or events,   *)
(* check that you have included the proper notification flags here.          *)
 
(* CloseGraphics should not be called until you close ALL the Windows and    *)
(* Screens opened with the above procedures. Otherwise...                    *)
 
(* If you want to open Windows and/or Screens without using these procedures,*)
(* you should assign IntuitionBase and GraphicsBase to UserIntuiBase and     *)
(* UserGraphBase, resp. This allows you to use the libraries opened in the   *)
(* procedure OpenGraphics as opposed to opening your own versions of these   *)
(* libraries.                                                                *)
 
(* The order in which these procedures is called is as follows: OpenGraphics,*)
(* {{CreateScreen}, {CreateWindow}}, CloseGraphics.                          *)
 

END WindowTools.
