7/15/96:  WarCart 057 development
          The following notes are quite out of date, but rather than revise them, I will
          wait until I'm ready for a full release of WarCart.  In the interim, I thought
          that you may enjoy playing around with it.  A number of things have not been
          implemented (sigh) yet, so I will be trying to work on those in between research
          and racquetball...
          
          Please do not redistribute this release of WarCart (as it is not yet considered
          finished).  Also, as this is still a development version, it will be more prone
          to crashes and the like than a final release -- back up anything that  you
          consider important.
          
          Matthew Hills
          
          
		 7/11  Bug Fixes:
		    Done:   Removed inlines (was crashing in PPC builds)
		            switched tool palette to CModWindow (to save position)
		            put strategic map into regular window level (no floating to prevent
		               targetting problems for the map window)
		            updated CWCMapView::DoPencil() to always post dirty message
		            deactivate CModWindow on Hide() s.t. controls will redraw when Show() is
		               called (during ToggleVisible())
		 6/30
		    Done:   Fixed Strat DrawRegion (was not copying all of background)
		    		Fixed overlay drawing (for roads) in MapView
		    		PPC native
		    
		 4/9
		    Done:	Fixed beeping when clicking on city. (was resetting tlCell in
		               MapView::ClickCity)
		    		Prohibit changing allegiance of a capitol city
		    		Pass on capitol city movements to the side editor
          



/*
 *  WarCart User Notes
 *
 *  matthew hills
 *  last revised: 3/3/96
 
Disabled features as of this writing:
  - Intelligent terrain
  - auto-road
  - most of the serious item editing (city stats, etc...)
     (the only portion of these that is editable is the description)

Basic Operation:
----------------
In this current version, WarCart is primarily a map terrain editor.  In
this section I want to convey how I intend it to be used, and then afterwards
come a lot of little details.

The primary focus for now is on the map (and strategic map) windows and 2
"palettes" -- the terrain palette and the tool palette.

The terrain palette window consists of two regions.  Across the bottom are
10 boxes filled with terrains.  I call this the "quick palette."  Above it
is the bulk of the available terrain in a terrain set (from now on, I will
refer to this as the "terrain palette").  Clicking or pressing a number key
with the cursor over the terrain palette will put the underlying terrain into
the appropriate quick palette slot (the mouse button inserts in slot '0',
and the keys insert in their respective slots).

The tool palette currently has the following tools:
	============================================================================
	=  Tool        Hot Key       Function                                      =
	= ------------------------------------------------------------------------ =
	=  Pencil      (ctrl)        place terrain under cursor                    =
	=                             (mouse button to use the '0' slot,           =
	=                             or can use a number key for another slot)    =
	=                                                                          =
	=  Dropper     (option)      pick up terrain under cursor                  =
	=                            (mouse button to use the '0' slot,            =
	=                             or can use a number key for another slot)    =
	=                                                                          =
	=  Arrow       (command)     select region                                 =
	=                                                                          =
	=  Anchor       -none-       place/remove port (only on shores)            =
	============================================================================

Clicking on the strategic map will scroll the map window to center on where you
clicked the mouse (just as in Warlords II).  Pressing command will change the
cursor to an arrow and you can then select a region... (this is helpful for when
you want to select a large region).  [I considered having all of the tools retain
their respective functions in the strategic map window, but the "center map window"
function was by far the most useful...]

Map window:  what happens here depends upon the selected tool.  There are some
menu commands that operate on this as well... in particular, cut/copy/paste/clear
in the Edit menu, as well as "Edge Selection" and "Fill Selection" and "Toggle Zoom".
[Q:  do you find the zoomed-out mode to be useful?]

Preferences:  The edging preferences should be straightforward (which terrain types
are edged).  You can also choose which terrain type fills in the background during
a cut or clear...  The weirdo here is a frivolous thing I threw in--if you copy
a selection of the map, a picture of it can be placed on the clipboard.  (drawing
the picture seems to require a great deal of memory, however, so this doesn't always
work and you will just get a boring picture with a message to that effect)

Weirdnesses:
------------
  - For you, the map editor, terrain will exist in 3 layers.
    These layers are:  base, road, and special.
    (this isn't the exact data representation stored in the files, but
     this is how I'm approaching it conceptually)
    
    Base terrain--stuff like water/land/trees/hills/mountains/swamps.
         This is the basic terrain you will be working with.
    
    Road terrain--this sort of "floats" above the base terrain.
         The palette shows road segments on white background--if you
         place these, the road will simply be placed on top of the
         existing terrain (hills or whatever).  Some effort is currently
         made to prevent illegal placements (you can't place on water,
         for instance)
         (ports are treated like roads--except you use the port icon to
         add/delete them -- only on shoreline spaces, however)
         
    Special terrain--signs, cities, temples, ruins, and strongholds.
         these terrains have extra data associated with them (you can
         see some of that data via the other editor windows -- I will
         soon be adding to this)
    
    The following editing rules are (or will be) enforced:
      - placing base terrain over road terrains will remove the road.
      - placing road on base is an overlay process
      - cut/copy/paste/clear operate on base and road terrains,
        but not on special terrains.
      - special terrains will ultimately be added/deleted by some other
        mechanism (to be decided), and moved by clicking on them and
        dragging (with the pointer tool)
        
  
  - pasting requires a cell to be selected
    (I have written code that will track the mouse with a
    gray box until the user clicks, and I could place the
    terrain that way.... which do you think is better?)
    (It would be possible, although tough, to do what most bitmap
    editors do--paste to the last cell clicked, and then allow the
    user to drag the selected region around...  ugh)
 
  - Keep a close eye on which terrains the dropper and copy/paste give
    you -- I've got a number of lookup tables floating around,
    and they were all hand-generated, and mostly late at night.
    (ie--prime breeding ground for bugs)
 
  - A continuous mouse-based draw using the pencil tool may be undone.
    (ie--if you press the mouse button and drag around).  Unfortunately,
    holding a key down and dragging around is not undoable.  (the last
    key-based placement may be undone...  big deal)
    
  - I couldn't decide on the best way to do a number of things, so stuck
    them in "Preferences" (in the Edit menu).
    
  - Auto-edging has been disabled as I backed up and rethought how I should
    approach edging.  "Edge Selection" typically requires that terrains
    have a thickness of at least two.  (the base terrains are:  sea/coast,
    forest,hill, and mountain...)  (I haven't implemented auto-edging on
    mountains, because I can't distinguish which mountain terrain tiles
    correspond to which edges/corners ;-)
    
  - the terrain file (grasslands, mud flats, etc.) you use to edit the map with
    will only affect how it is shown in the editor--and not in Warlords II... or
    in the strategic map window, for that matter.
    
  - WarCart erases the strategic map from the scenario file when the file is
    saved, as Warlords II will recreate it from scratch (and theirs looks better)
    
  - There is currently some weirdness related to moving the mouse over the
    terrain palette (in particular, you can't do "command-f" to fill (etc...))
    To execute these commands, move the cursor back over the map.
    (I am looking into the best way around this)
    
 
Comments to You, the Tester:
----------------------------
   - Most things are done the way they are for some reason... but sometimes that
     reason is only that "I haven't decided on the 'right way' yet," so don't
     hesitate to let me know how you think the editor *should* work.  As you are
     using it, consider what impulses you have or what things you keep wishing
     were available.
     
   - This is a development version.  Please do not redistribute or discuss this
     program in a public forum.  (If you think someone would be helpful to testing
     this program, let me know and I'll gab with them)
   
   - Let me know of *any* crashes, and especially of any repeatable crashes.
     If you can find such a thing, let me know the following:
         - computer stats (type,physical memory, system version)?
         - are you running ram doubler?  (any weird extensions?)
         - does the crash not occur if more memory is allocated to WarCart?
     (I ask these questions to help narrow the scope of my bug-search... 
      WarCart should be stable under all conditions--and exit gracefully if there
      is a problem)


  Some interface questions that occur to me right now:
    ?:  At times I found myself making a selection then clicking on the palette,
        expecting it to fill...  (this is pretty bad, as I programmed it, and
        should know better) -- is this a reasonable paradigm, or would you find
        yourself making errors by doing this?  (ie--intending to click on a
        terrain to make it the currently-selected terrain and inadvertently
        filling your selection?)
    ?:  Should clicking on a terrain in the quick palette have an effect?
    ?:  Currently, "Edge Selection" pulls all of the edge stuff from the Preferences.
        Would it be worthwhile to have menu items for each one independently?
        ("Edge Hills,"  "Edge Forests," etc)  <-- this seemed kind of cluttered to me,
        so I wasn't sure.
        
*/

---------------------------------------------------------------------------
  *    War Cartographer:  Development Release
  *    February 9, 1996
  *    Matthew Hills
  *      hills@sensors.stanford.edu
  *
  *    Support Site:  http://www-leland.stanford.edu/~hills/games.html
---------------------------------------------------------------------------

              ==> DEVELOPMENT RELEASE: DO NOT REDISTRIBUTE <==

Introduction:
=============

  War Cartographer (hereafter "WarCart") is a scenaio editor for the
  macintosh version of Warlords II.  There is an earlier program (War
  Correspondent) for editing army files and the item databases in the
  scenarios.
  
  Necessary disclaimer:  the development release is very crude and is not
                         guaranteed (or expected) to run reliably.
                         
                         Please do not redistribute this development release
                         without my prior consent. (I am trying to minimize
                         the number of grossly buggy programs in general
                         circulation)
                         
Instructions:
=============
  Hey guys (to Jim and Nunzio):
    - This is a very early draft, as I haven't had much time to work on it.
      I'm sending it out now to give you something to play with and to hopefully
      catch any bugs that might be slipping through...  I haven't tested it
      heavily in conjunction with WarLords II (ie--I think I have stuff figured
      out, and then get it so WarCart does what I want, hopefully without crashing,
      then release to you guys)  -- Warlords is quite slow on my IIci (my development
      computer right now)
      
    - Oh, on bug reporting -- there are quite a few things that "don't work right"--ignore those
         for now.  I'm primarily interested in:
               * crashes
               * things that are supposed to work, but don't
                   (such as "sticking a port here doesn't have any effect," or
                    "the computer doesn't recognize the terrains I'm moving on to)

    - The first time you open a scenario, you will be given a second "Open File..." dialog
      box -- this is to locate a scenario file.  (the file is subsequently saved in Preferences,
      so this should only happen once) <-- this will change
    - the SCEN editor is very minimal and doesn't save anything.
    - the map editor should be able to edit and save stuff.
    - on the toolbar:  the pencil is for editing, the select box and city tools
      aren't yet implemented.  The anchor plugs down anchors wherever and whenever.
      (I think that this works okay--please check this one -- this is stored in the
      MAP resource, which is very simple in the original scenarios, but has all sorts
      of garbage in it for the random scenarios (the trouble is, I'm not sure it is
      garbage, so I try to preserve as much as possible))
    - on the terrain palette:
        The idea is that clicking on a terrain in the palette will set the '0' slot
        with it.  (the '0' slot is what the mouse will place if you click on the map)
        The other slots are what you get if you press that key over the map
        (this is to provide something of a shortcut) -- I plan to put a small pencil
        icon above the '0' to indicate the dual functionality... (comments?)
    - Roads...  roads are in a separate resource right now--I just haven't figured out
        what would be an appropriate editor for them.  Do you really want another palette
        like the terrain palette, but for roads?  (another option would be automatic
        "smart roads" -- where the roads figure out which other roads are around, and
        automatically adjust to make all possible connections (it isn't clear that this is
        better -- and it wouldn't work well with the signpost roads, etc...))
    - Cities--currently cities aren't edited, although you can stick their graphics all over
        the place.  Probably better not to.
    - Multiple File support is inconsistent right now -- I'm trying to decide what is the best
        way to implement this...
    - I'm thinking about just erasing the information that is in the Random scenarios, and
        trying to stay with a consistent format like I get with the original scenarios.
        (ie--'RD  ' only has data on roads--no garbage junk; 'MAP ' only has terrain & anchors,
        none of the extra stuff, etc.)
    - What things do you want saved in Preferences?  (I can store all sorts of junk, such
        as which windows are initially visible, window coordinates, etc.)
    - How do you want me to look for scenario (and other data) files?
         ==> ask the user for them every time
         ==> ask the user to locate the Warlords II directory, and search that and subdirectories?
         ==> scan all the directories on the hard drive?
         (any other ideas?)
    - For terrain editing, do you want access to every type of terrain, or just terrains
         that make sense (ie--I could make things like the city icons unavailable for general
         editing, and restrict usage to standard terrain types (plains, forest, hills, etc.)
         (obviously, it would be extra work--is it worth it?)
         
  
Future Revisions:
=================
  
  ==>  LET ME KNOW OF ANY DESIRED FEATURES/BUG-FIXES!
       (and especially user interface suggestions)
  
            
Acknowledgements:
=================

  Jim Flanagan (VineStreet@eWorld.com)
  Nunzio DeFilippis (matusek@aol.com)
        - early testers and heavy contributors to the decoding of the
          unit files. (as well as general encouragement)
        
  c.s.m.p.cw residents
        - for patience and some good suggestions as I picked up powerplant.

Who I Am:
=========

  An EE graduate student, majoring in racquetball (I wish)... but mostly I'm
  found in the cleanroom or some-such.  (My research is on micromachined 
  electrodes for measuring nerve activity within the brain cortex.  I am
  currently looking for a few good volunteers ;-)
  
  Over a year ago, I wrote War Correspondent as an excuse to put off studying
  and to learn C++ and TCL.  Since then, I've forgotten almost all of my C++,
  so had to pick it back up again, and have also switched to PowerPlant. My
  first program in this framework was AGadc (Allied General Aide de Camp).
  WarCart was developed because SSG still has not released a scenario editor
  and I'm in love with PowerPlant and just can't seem to sleep...



---------------------------------------------------------------------------
  *    Appendix 1:  Development Notes
---------------------------------------------------------------------------
 
 Development Notes
 -----------------
  (separate for now)