COLORUTILITIES Quickie User's Guide
Revised:  March 27, 1984 by Ken Feuerman (Feuerman.pasa)

COLORUTILITIES.DCOM is a set of functions for the 1100 which allow a user to create windows and menus on the color screen.  This file should be loaded AFTER {PHYLUM}<LISP>LIBRARY>COLOR.DCOM had been loaded.  Please see {PHYLUM}<LISP>LIBRARY>COLOR.TXT for important information about the needed hardware for color.

Color Windows

Color Windows are not quite the same as their black and white counterparts.  A Color Window is a window with certain properties that make its display appear on the color screen.  By definition, they are transparent on the color screen; i.e., overlaying one window on another on the color screen will not obliterate the bottom window.  Therefore, displays to color windows can get confusing if the windows are overlapping.  When you create a color window, you are asked for a border color.  This color becomes the "resident" color; i.e., all display operations to that window appear in that color unless specified otherwise.  Also, the window menu for color windows (press the right button while in a window) appears in the color of the border color.

New Background Menu Commands

There are three new Background Menu Commands which allow for easy turning on and off of the color screen, the black and white screen, and switching the cursor between screens.  The Background Menu is the menu that pops up whenever the right mouse button is pressed outside of any window.  The commands are:

   Switch:  Switches the cursor from the black and white screen to the color screen, or vice versa.
   Display On/Off:  If the black and white screen is on, it is turned off.  The color screen is turned on (if not already on) and the cursor is moved to it (if not already there).  If the black and white screen is off, it is simply turned on.
   Color Display On/Off:  Same as Display On/Off, only for color screen.

Note:  Using the above menu commands, it is impossible to have both screens off at the same time or to have the cursor on a screen that is turned off.

With that brief introduction of what to expect differently in color, here are the important functions to create color windows and display menus in color:

(COLORCREATEW Region Title Bordersize Bordercolor RedisplayWhenCloseFlg) --  Creates and returns a color window, and displays it on the color screen.  If Region is NIL, the user is prompted for one as in CREATEW, only the prompting occurs on the color screen.  Default Bordersize is 4, default Bordercolor is 15 (after loading COLORUTILITIES.DCOM, color 15 is WHITE). 

RedisplayWhenCloseFlg indicates whether REDISPLAYW should be called when closing the window.  This is very handy if the REPAINTFN for the window uses INVERT as its DSPOPERATION (a good suggestion, INVERTing is more easily displayed and un-displayed when dealing with transparent windows), so that its display will be wiped clean without destroying the contents of other perhaps overlapping windows.  If RedisplayWhenCloseFlg is NIL, the user should make sure to clear the window before closing it [either manually or by specifying (WINDOWADDPROP WINDOW 'CLOSEFN (FUNCTION CLEARW))], otherwise its display will be left up on the screen.  Note that when clearing a color window, any overlapping windows will have their overlapping regions destroyed.  Selecting Redisplay on the right button color window menu will restore its border and call the window's REPAINTFN.

(MENU Menu Position ReleaseControlFlg) -- This is a redefinition of the standard MENU function.  Behaves exactly the same way as before if the cursor is on the black and white screen.  If the cursor is on the color screen, the pop up menu appears on that screen.  Position defaults as before.  ReleaseControlFlg is not implemented yet.

There are several ways to determine the color of an item in a menu.  The first check is in the item itself.  If in the list which describes an item there is a list whose CAR is the atom COLOR, the color of the item is retrieved from the CADR or CDR of that list, whichever happens to be there.  If not, then the color of the item is the color of the menu outline.  This is determined from a property of the menu (NOT a field).  To enter the color of the menu outline, perform (PUTMENUPROP Menu 'MENUOUTLINECOLOR Color).  The default color here is (MAXIMUMCOLOR).  To give an example:

(SETQ COLLEGEMENU
	(create MENU
		ITEMS ← [LIST
	(LIST 'POMONA '(POMONA.FN) "Runs Pomona function"
				(LIST 'COLOR 'BLUE))
	(LIST 'CMC '(CMC.FN) "Runs CMC function"
				(CONS 'COLOR 4))
	(LIST 'HMC '(HMC.FN) "Runs HMC function")]))
(PUTMENUPROP COLLEGEMENU 'MENUOUTLINECOLOR 'GREEN)

This will create a menu with a GREEN outline and with three items.  POMONA will appear in BLUE, CMC will appear in color number 4, and HMC will be in GREEN (from the outline color).

The Menu argument is otherwise very much the same as black and white menus, with the exception that some of the menu fields controlling display and such aren't implemented in color yet, so these fields are ignored for now.  Those fields are:
    WHENHELDFN - Currently nothing happens when a button is held. 
    WHENUNHELDFN - Similarly nothing.
    MENUPOSITION - Behaves same as though this were NIL (regardless if this was actually specified).
    MENUBORDERSIZE - Always treated as 0.
All other fields (ITEMS, WHENSELECTEDFN, MENUOFFSET, MENUFONT, TITLE, CENTERFLG, MENUROWS, MENUCOLUMNS, ITEMHEIGHT, ITEMWIDTH, MENUOUTLINESIZE, and CHANGEOFFSETFLG) are treated the same as they are normally.  The same menu should be usable on both the monochrome and color screens.

(ADDMENU Menu Window Position) -- Only if Window is a color window is Menu made into a menu on the color screen that remains active in a window.  If Window is NIL or is a normal window, this function behaves the same as before with Color ignored.  The same comments above about Menu apply.  Returns the window to which Menu was added.

(COLORMENU Menu Position ReleaseControlFlg) -- Forces Menu to appear on the color screen.

(COLORADDMENU Menu Window Position) -- This time if Window is NIL a color window is created first and then the Menu is added.  Unpredictable if Window is not a color window.

(COLOREDITBM Bitmap) -- Make sure that Bitmap has 4 bits per pixel (that it is in fact a color bitmap).  This will open a color bitmap editor window on the color screen.  Operations on this bitmap editor work pretty much the same as on the black and white screen, with a few exceptions.  Left button lights up a grid square in the currently selected color, middle resets it to its previous color, right button erases it to black altogether.  Moving the cursor up to the shaded area across the top and pressing either the left or middle button brings up a command menu with six options:
	Reset -- Returns the bitmap in the grid to its state at the beginning of this edit session
	Clear -- Clears the bitmap to black
	Move -- If the bitmap is too large to completely fit on the grid, Move allows the user to specify which region to put in the grid.
	Color -- Sets the color currently being drawn when pressing the left button.  The shaded area across the top changes to match that color.
	OK -- Finished, save changes
	Stop -- Finished, don't save changes
The returned value is the color bitmap that was edited.



Some other useful functions are:

(GETCOLOR) -- Puts a pop up menu on the color screen (make sure that the screen is on) and allows the user to select from 15 colors displayed in rectangular regions (color number 0 is left out).  Returns the color number of the color selected, or NIL if none is selected.

(GETCOLORREGION) -- Analogous to GETREGION, only the "ghost" region being swept out appears on the color screen.  Returns the resulting region.

(COLOR.CREATE.TTY Region Color) -- Creates a color window of color Color (default 15) on the color screen occupying Region (if NIL, Region is prompted for), and assigns that window as the top level typescript window.  Returns the old TTYDISPLAYSTREAM.

(COLORGETBOXPOSITION Width Height) -- Similar to GETBOXPOSITION, only the "ghost" region appears on the color screen.  Returns a POSITION in the coordinates of the color screen.

(COLORGETBOXREGION Width Height) -- Same as COLORGETBOXPOSITION, only it returns the region occupied by the box of width Width and height Height.

(COLORIZE.SCREEN.REGION Sourceregion Color TargetPosition Operation) -- Blts a region specified by Sourceregion directly onto the color screen with origin at TargetPosition.  Operation determines how the bits on the color screen are merged.

(COLORIZE.WINDOW Window Color TargetPosition Operation) -- Puts an image (not an actual window) of Window on the color screen in color Color at TargetPosition using Operation.

(SWITCHSCREENFN) -- The function that is called by the Switch option off the Background Menu.

(SWITCHDISPLAYON/OFF) -- The function that is called by the Display On/Off option off the Background Menu.

(COLOR SWITCHDISPLAYON/OFF) -- The function that is called by the Color Display On/Off option off the Background Menu.





Any comments or suggestions welcome.