===============================================================================
-------------------------------------------------------------------------------
----------------------J A Z Z B E N C H  (alpha 0.8)---------------------------
-------------------------------------------------------------------------------
===============================================================================
    
    Welcome to my Workbench replacement program!  I haven't decided on a
    name yet, but I've tentatively named it JazzBench.
    
        JazzBench (0.8) Copyright 1989 by David Navas
        ALL RIGHTS RESERVED.
        
    Of course, this will have to change as code is written by other people,
    but all of these details can be worked out later (unless someone
    else finds some pressing need...).
    
    
    Starting up:
	0) copy <this disk>:libs/ppipc.library libs:
        1) assign wb: <this disk>:wb
        2) wb:wbsetup
            This works much better if done BEFORE loadwb has executed...
		(suggestion -- put it into your s:startup-seq.)
	3) wb:wbaudio wb:hal9000  (for a cool beep...)
    Caveats:
    
        The code for this set of programs does not comfortably fit into 
    a 512k computer.  If you've got a 512k computer -- return my disks!
    (sorry, maybe we can work out something when code has been translated
    into assembly...)  Actually -- try running the program without
    wb:WBrefr, wb:wbcal, wb:wbabout, etc., and wb:WBaudio.
    In order to accomplish this, edit the file wb:startup and erase the line
      with wb:wbrefr, wb:wbcal, etc., leaving only WBserver, WBwindow,
      and WBinput.  Don't execute the wb:wbaudio command.
    Do the words I wanna Fat AGNUS ring a bell with anyone?   sigh.
    
    

    The programs:
        1] WBsetup -- is now responsible for sending properly placed
            default images, etc. to wbserver.  It opens the backdrop
            window and attaches the default Menu to it.  It then starts
	    WBdisk.  Searching the startup file it starts whatever programs
	    it finds there.  It then waits for WBserver to request all of
	    WBsetup's default material, and then passes it on.
    
            WBsetup opens a default configuration file and get its default
	    images, programs-to-start, etc. from there.
            See info on MenuItem 'LibEdit', for whatever further information
	    is available.

        2] WBserver -- handles all message passing between the different
            WorkBench programs.  It is the program which handles all of
            the interpretation of IPCMsg Ids, and figures out to which
            programs what messages will be sent.  This is where hooks
            have been attached to intercept certain types of Ids and send
            them to some custom program.  (See WBcool)

        3] WBwindow -- in theory, handles Window graphic activities.  All
            scrolling (selected icons and window icons), Icon placement &
            display, and window OPENs are done here.  However, not all
            the DrawImage()s are done here.  Some errant ones may still
            be done in WBdisk (when the backdrop disk icons are removed).
    
            For the most part, WBwindow is complete and in its final form.
            The code has been drastically cleaned (no more 3 page-long
            if-then statements...).  I don't see how much else will change.
	    Probably will display more info about files under TEXT windows.

        4] WBinput -- obviously handles all IntuiMessages sent to the
            JazzBench IntuiPort.  Has some (perhaps) curious flags which
            keep track of MouseMove messages:  when another message is
            available;  what window ReportMouse activated;  etc.  This is
            very important as all refreshes occur here as well.  This
            ought to be a message handled by WBwindow -- and will be.
            Unfortunately, every once in awhile my program and Intuition
            appear to fight over who reigns over refreshing, and the
            window borders remain unrefreshed.  I believe it has something
            to do with what I'm doing with Begin/EndRefresh(), but I'm
            not sure.  Any bug fixes -- or firm ways in which to get this
            to reoccur are welcome.  (I believe this has been fixed since
		last version)
            WBinput also handles the stripping of the MsgPort, Menus, etc.
            before a window is closed -- and puts this same information
            back into the window structure when it is opened.

        5] WBdisk -- currently referred to (fondly?) as THE MONSTER.
            This is the program that needs the most attention, before
            it makes the disk too heavy to lift ;-}.
    
            Anyhow, WBdisk takes care of all disk copies, renames, deletes,
            directory searches (valid form, and fastdir method from Amazing
            Computing), icon retrievals, etc.  It is also in charge
            of Trash emptying (just a delete, right?), icon saves, and
            other stuff that I'm sure exists but doesn't come to mind
            right now.
    
            There are at least two bugs in this program.  It doesn't
            react properly to the 1.2 RamDisk.  Rename sometimes doesn't
	    return the error code correctly.
    
        6] WBlist -- an outdated program, now that Hidden (the MenuItem)
            works.  It lists the directory of the window in which you
            press the HELP key.  Cute, but only useful for some debugging
            operations now.
    
        7] WBcool -- gives that MKnTOSS (:-)) look for the opening/closing
            of windows/icons.  Mostly a demonstration of some code
            for intercepting messages.
    
        8] WBrefr -- intercepts the refresh message and acts accordingly
            with the knowledge that there is now a patterned backdrop
            on the BackDrop window.  I suppose this could be enhanced
            to include putting an IFF picture onto the background.
    	8.5] WBcolrefr -- same as WBrefr -- different pattern  (really
	    hideous).

        9] WBaudio -- reads in a binary dump of an audio sound and sends
            the new data to WBserver to serve as JazzBench's new beep
            sample.  I like HAL9000 myself (being a Dave...).

	10] WBabout -- the about window demoing graphic menu additions

	11] WBleodie -- In the tradition of Leo Schwab (forgive my
	    misspellings), a cute way to kill a window when it's
	    closing.

	12] WBiconize -- iconizes the current window.  Needs to put the icon
	    in a more visible place.  (Shoot, it needs a real icon,
	    really).  Currently some text of the icons end up to
	    the left of the screen.
    
        
    Usage:
    
       Well, all menu items are always on -- although that is perhaps not
    the best way of doing things.  If something is not available, JazzBench
    will beep.  Notice the lack of a ZZpointer.  The only
    time that you are prevented from getting an immediate response from the
    program is when the program is LoadSeg'ing another program, or WBdisk
    is trying to do a copy to prt: or something that takes a long time --
    although input requests ARE queued (be patient...).
    
    Menus:
    USER:
      custom programs put menuitems and stuff here.
    FILE:
      OPEN -- opens the current Select List.          Amiga-O
      CLOSE -- closes the active window.
      COPY -- copies selected objects.                Amiga-C
      RENAME -- renames first object on Select List   Amiga-R
      DELETE -- deletes all objects on Select List    Amiga-X
      INITIALIZE -- the disk format
      MAKE DRAWER -- makes a directory with	      Amiga-M
		default icon
      ASSIGN -- will assign <selected object's name>: Amiga-@
                to the object.
      EXECUTE -- executes script with IconX

    SYSTEM:
      EMPTY TRASH -- obvious
      CLIPBOARD -- the non-existent program which
      		    I'd like to have show clipboard contents.
		    (Anyone want to write one?)
      INFO -- hey, talk to David S. King about this one.
      LIBEDIT -- edit the config and startup files which define
      		  startup conditions:
	Device Copy:  am't in bytes to transfer to a non-disk format (eg.
			prt:)
	File Copy:    am't in bytes to transfer between disks at one time
			 interval
	Menu: MenuTitle.  Use arrows to scroll.
	Item: Title (if TEXT!)  Use arrows to scroll.
	Command: keyboard equivalent of current MenuItem (if any -- bug if
		Item not TEXT)
	Assign:  command the ASSIGN menuitem calls.
	DiskCopy: not used -- DiskCopy gets it's default ToolName from the
	  DefaultTool in the Disk Icon.
	Format:  command INITIALIZE calls.
	INFO:  Not used, really.
	LibEdit: the program LibEdit runs.
	New Drawer -- title of new drawer that MAKE DRAWER creates.
	Title -- screen title.
	Startup -- list of files started on entry.  Must include WBwindow,
		WBinput, WBserver!

      LAST ERROR -- displays last error		      Amiga-E
      VERSION -- displays version		      Amiga-V
      STOP ALL COPYING -- stops any copying the
      		program is doing.
      SHOW DEVICES -- shows devices available

    ICONS:
      SHOW HIDDEN ICONS -- shows hidden icons..       Amiga-H
      SHOW TEXT -- show icons as text titles only     Amiga-T
      ORIGINAL ICONS -- show normal icons only        Amiga-N
      ALPHABETIZE -- alphabetize the text-only	      Amiga-A
      			windows
      SNAPSHOT -- due to user demand, I'd like a      Amiga-S
        mask to determine just what information to
        save, and what information to leave intact.
      REDRAW -- redraw, refresh window/gadgets
      CLEAN UP -- reorganize icons.
      PUT AWAY -- ever want to rid youself of those   Amiga-P
   	pesky icons you've left on the backdrop window?
	Well, PUT it AWAY...
      CYCLE COLORS -- change window colors	      Amiga-=
    

    Interesting stuff:
      SHIFT-CTRL-LEFTMOUSE unselects a selected icon without loosing
      	the rest of the selected icons.
      Drag-starts.  Drag POroject onto Tool.
      
      There are 12 ways to add ports and intercept messages from WBserver:
         GADB, GADA -- intercept GADG, GADU, GADD, DOUB, MOUS, CLOZ messages
	   (Before/After) WBserver does its 'thing'
	   GADU -- GADGETUP
	   GADD -- GADGETDOWN
	   GADG -- obj selected
	   DOUB -- open this obj
	   MOUS -- MOUSEBUTTONS
	   CLOZ -- CLOSEWINDOW
	 MENB, MENA -- intercept all Menu commands.
	 KEYB, KEYA -- intercept all RAWKEYS
	 REFB, REFA -- intercept REFRESHWINDOW
	 DSKB, DSKA -- intercept DISKINSERTED/REMOVED
	 WINB, WINA -- intercept Window Open events (window already open --
	 		intercept before/after WBinput and WBdisk changes
			UserPort/gets directory/etc.
	 see ipc.h, WBserver.c, and example programs for implementation
	 		details.
      

    Known Bugs:
       Locking problems with 1.2 Ram Disk.  (get 1.3...)
       Disk whirs a lot when deleting lots of files.  Not a bug, just getting
       	all the necessary locks.
       WBLibEdit -- Command key not recognized if MenuItem not TEXT upon
       			startup
       Rename does not return the correct error code.
       WBcal does NOT work completely well with A1000 keyboards --
       	no divides/multiplies.  Fix as you'd like.

    To be added:
    
       WBLibEdit needs to be made pretty printed.  
       Better support for text listings/edits.  (see BackDropPass in jb.h)
       WBserver needs to be cleaned as far as ports/names are concerned.
			(why is a CLOZ sent within a GADG scope? -- I don't
			 know either, it seemed best at the time...)
       WBdisk may get better hooks -- need to compress COPY code.
       WBiconize needs to be prettied-up.
       WBaudio/server needs layering (multiple sounds for different msgs)
       WBserver port adds need to use ln_Pri bits.
       TEXT windows will display more info about the files (creation dates/
       		etc.)
    


    Compiling:
	Unlike the rest of the world, I haven't learned how to use make files
	   efficiently -- so here's how to compile my program.

	If you can precompile jb.h, that'll help, otherwise uncomment the
	   #include "jb.h" in the program.
	You will need ipc.lib for linking all programs
	   which use the ipc functions (as in, all of these programs...)
	Now compile the program and link in with ipc.lib

	Note: please use long (32 bit) integers
	
    Writing support routines:
	For a good idea of what goes on, see WBserver.c.  You may
	    intercept six kinds of messages -- refresh, raw keycodes,
	    menu operations, disk inserted/removed, window opened, 
	    and gadget type messages.  You may intercept these messages
	    either before or after the program is done with them.  The Id
	    to pass in the IPCMessage is something like GADA, GADB (for
	    GADget After, GADget Before), MENA, MENB, etc.  To remove, the
	    Id will look something like RMEN, RKEY, RREF (for Remove MENu,
	    Remove KEY, Remove REFresh).  See ipc.h for IPCMessage format.
	     Also see example programs

	You might try an online HELP guide to the program.  Or even nioer,
	    a menu item to reload the directory of an already open window.
	    Be careful to de-allocate the previously allocated directory
	    list stored in obj->wo_DrawerData->dd_Dir.  When the menuitem
	    is selected, dd_Dir is cleared and freed, and a WIND message
	    is sent to WBserver.  Now that I think about it, I might just
	    write it to see how it works.

	Try using the GlobalInfo (reported back from server when you 'RINF'
	                          it [puts into msg->ipc_Items[0].ii_Ptr]) 
	    ->showtext to write a simple showtext.  IE. program puts
	    a menuitem into menubar with 'MIAL', waits for it to be selected,
	    then sends a 'RUN ' with Items[0].ii_Id = GlobalInfo->showtext,
	    and Items[0].ii_Ptr = GlobalInfo->Select;

	Experiment, and REPORT BUGS!!!

    
    Until next time, ideas, etc. welcome at:
    
    David Navas
    1918 Hackett Ave.
    Mt. View, CA 94043
    (415) 967-2382  (voice only -- unless some kind gent wants to donate
                     a modem...)
    you can try to send messages to c60c-1ea@WEB.Berkeley.Edu  but that
	account closes in June, I'll try to post new accounts later.
    
    Thank YOU very much for your time and effort in this project.
    Hopefully others will appreciate it also -- and not to far off either...
    
    
    
    Many thanks go to the author of Hackbench, without whose code I would
	not have had the guts to write this program (and no idea of
	how to write some of it).  Also my deep thanks to Dave H. who
	wrote the fastdir algorithm making those idiot .info files
	found in all directories to be pretty much useless and
	unnecessary.  And last but not least, thanks to Pete Goodeve and
	Peter da Silva for thrashing out the IPC code used for all of
	my communication needs.

    All code compiled by Manx 3.4a compiler -- feel free to modify to
	whatever extent necessary in order to work with other compilers.


					Until next we meet,


					David Navas
