
                     -------------------------
                         Mouse-Ka-Mania II
                     -------------------------

             (or, Return of the Son of Mouse-Ka-Mania)

                  Shareware by Charles F. Johnson
                1994 Little Green Footballs Software
                       All Rights Reserved.

                           Version 2.0



                          INTRODUCTION
                          ============

In those early days (or so it was written), Walt begat Mickey, who begat
Shemp, who begat Lenny, who got quite uncomfortable.  Mice were composed
of single, lonely frames (yea verily, one IS the loneliest number), and
were despondent, and gnashed their tiny teeth.  But lo, to the amazement
of all, onto the scene burst, Lazarus-like, the resurrected Mouse-Ka-Mania
II!  And all Ataridom wept copious tears of delight to behold its elegance,
its ingenious simplicity, its ...  utter uselessness!??

Yes, my friends; it's true.  You may or may not have been waiting seven
years for this, but here it is anyway!  Mouse-Ka-Mania, long one of the
best mouse shape editors (and the only animated mouse installer!) has been
rewritten, revamped, retooled, and hypercharged for the fantabulous
nineties (sheesh, did I really write that?) with tons of new features and
new capabilities, compatibility with Geneva, and more and more and more. 
This, friends, is a mouse editor on mega-steroids.  It may be ultimately
about as useful as a pet rock, but garsh gee whillikers, it shore is fun. 
Read on, if you dare. 


                  COPYRIGHT / ABOUT SHAREWARE
                  ===========================

Mouse-Ka-Mania II and the accompanying files are Copyright 1994 Little
Green Footballs Software and Charles F. Johnson.  All rights reserved. 

The archive containing Mouse-Ka-Mania II may be freely distributed on
electronic bulletin board services and in user group libraries, under the
condition that all the files from this original distribution are included
and unaltered. 

Mouse-Ka-Mania II is distributed as shareware.  (Some people call this
"try-before-you-buy-ware"; please note that this is not the same as "use-
as-long-as-you-want-for-free-ware".)  If you like Mouse-Ka-Mania II, and
decide to leave it installed on your computer, please send a check or
money order for $15.00 to:

  Charles F. Johnson
  P.O. Box 1250
  Pacific Palisades, CA 90272

As little as $15.00 seems, those shareware payments really do make a 
difference.  It takes a lot of time, training, and expertise to write a 
program like Mouse-Ka-Mania II (even if, in this case, the idea is just to 
have a little fun instead of writing the Great American Spreadsheet), and 
your payment encourages me to spend more time in such pursuits.  I'm 
afraid I can't promise to answer every letter I get; I have very little free 
time these days, and am often out of town.  However I will make the latest 
versions of MKM II available as soon as they're ready, in the Atari areas 
on GEnie, Compuserve, and Delphi.  If you have a question about Mouse-
Ka-Mania II, the best way to get an answer is to contact me on 
Compuserve (76004,2232) or GEnie (C.F.JOHNSON or CODEHEAD).


                         INSTALLATION
                         ============

Mouse-Ka-Mania II is a GEM desk accessory.  To install it, copy the file 
MOUSEKA.ACC to the root directory of your bootup drive and reboot your 
computer.  Users of MultiDesk Deluxe or Geneva can load Mouse-Ka-Mania 
II any time they like, using the commands provided in those programs.


                          QUICK START
                          ===========

OK, you've installed Mouse-Ka-Mania II.  You probably want to see what it 
can do right away without reading the rest of this manual first.  Go ahead, 
you can admit it.  My feelings won't be hurt, even though I labored long 
and hard on this document.

So here's how to quickly replace all the standard mouse shapes with 
animated shapes.

1.  Open the desk accessory, by moving the mouse to the Desk menu and 
    selecting "Mouse-Ka-Mania II."

    The Mouse-Mania II desk accessory is where you create and edit mouse 
    cursors, assign them to the standard system mouse cursors, and load and 
    save single-frame and animated cursors.

    Notice that the arrow cursor is already selected in the row of cursors at
    the top of the dialog box.

2.  Click the button labeled "Load," at the lower left of the dialog.  An
    alert box will appear, asking which type of file you wish to load.  Click
    the button labeled "AutoMouse."

3.  Use the file selector to locate and select the file called AUTOMOUS.PRG, 
    which is included with the MKM II archive.  That's right; even though the 
    file has a PRG extension -- meaning it's an executable program -- you're 
    going to load it into the MKM II DA.

4.  Notice that your arrow cursor has now been replaced with a flashy 
    pulsating animated cursor.  But it isn't just the arrow; the AUTOMOUS.PRG 
    file contains animated shapes for all the standard mouse cursors.  To see 
    the other animations, click on the other cursor shapes at the top of the 
    dialog and move the mouse into the black/white box (the "preview box") at 
    the upper right.  When you move the mouse into the preview box, the 
    cursor changes to show the currently selected shape.


                      GENERAL INFORMATION
                      ===================

Mouse-Ka-Mania II runs on all Atari computers.  The desk accessory dialog 
box is useable in all screen modes with 640 or more pixels of horizontal 
resolution, and any number of colors.  It has been tested (and works) with 
the Crazy Dots graphics board, and should work with other boards too.  You 
may notice that the shape editing functions are much faster in modes with 
two or four colors (one or two bit planes); this is because MKM II uses 
custom graphics routines for two or four color modes, and reverts to 
standard VDI calls for modes with more colors.

NOTE: Even though the MKM dialog box will not open in low resolution 
modes, the automatic mouse cursor replacement functions do work in 
these modes, so you can still install custom mouse cursors.

The Mouse-Ka-Mania II desk accessory uses about 65K of memory when 
installed.  If memory is short, however, MKM II has a special feature that 
lets you install a full set of animated cursors while using the absolute 
minimum amount of memory possible, and without using a desk accessory 
slot.  See the section titled "AutoMouse Programs" for details.

The MKM II desk accessory is in a modal window; that is, you can't bring 
another program's window to the top while MKM II is open.  Technical 
reason why this is so: because the editing functions use VDI mouse input 
commands, which would conflict with the strictly-AES approach needed to 
support a non-modal window.  Non-technical reason: so that the editor 
doesn't slow to a crawl.  However, MKM II does make regular AES "event" 
calls, so any background tasks (like downloading with STalker or STorm, 
for example) should be able to continue while the DA is open.

Another point to keep in mind: the MKM II desk accessory needs to grab 
several exception vectors to do what it does.  In English, this means that 
you may have problems if you change the resolution from the GEM 
desktop.  This is because GEM wipes the accessories out of memory when it 
changes resolutions, but doesn't tell them about it -- so they don't have a 
chance to clean up after themselves.  If you use CodeHead's MultiDesk 
Deluxe to load Mouse-Ka-Mania II you don't have to worry about this, 
because MultiDesk uses special techniques to avoid these kinds of 
problems.  Otherwise, it's probably best to use a bootup manager program 
like Desk Manager or Superboot, and reboot when you change resolutions.

Note that the caveats about changing resolution only apply to desk 
accessories; if you use the AutoMouse feature of MKM II, and don't install 
the DA, there is no problem with changing resolutions.


                 STANDARD SYSTEM MOUSE CURSORS
                 =============================

There are eight mouse cursors predefined in GEM:

1.  The ubiquitous, if rather unexciting ARROW.  This is the mouse cursor 
    you see most often, and is commonly used to point at menu items, click
    on buttons, etc.

2.  The TEXT EDIT cursor.  This cursor (sometimes called the "I-beam") is 
    used in text editors and word processors, to let you easily locate text 
    insertion points, mark blocks, etc.

3.  The all-too-familiar BUSY BEE.  This cursor usually appears during time-
    consuming operations, like spreadsheet calculations or disk access, to let 
    you know that you should sit patiently and wait until the computer is good 
    and ready.

4.  The POINTING FINGER.  The convention for this cursor has never been 
    spelled out; it's used sometimes as a substitute for the arrow.

5.  The OPEN HAND.  This cursor is commonly used to indicate "dragging" 
    actions, such as pulling files to the trash can, or moving objects around
    in a drawing program.

6.  The THIN CROSSHAIR.  Commonly used in paint programs to mark sections
    sections of a picture.  LDW Power uses this cursor for marking cells in
    the spreadsheet.

7.  The THICK CROSSHAIR.  Not used very much.

8.  The OUTLINED CROSSHAIR.  See THICK CROSSHAIR.

These eight cursors are shown in the form of selectable buttons at the top 
of the Mouse-Ka-Mania II dialog box.  MKM II lets you replace any or all of 
these squeaky old rodents with new, exciting, single-frame or animated 
cursors.


                   USING MOUSE-KA-MANIA II
                   =======================

Since the MKM II package comes with dozens of ready-to-use mouse 
cursors, you can just browse through them (with the "Load" command) and 
find ones you like.  But Mouse-Ka-Mania II also lets you create and edit 
your own mouse cursors from scratch, including multi-frame animations.  
And if you're a programmer, you'll be happy to hear that you can export a 
C, assembly language, or Basic source code file, to easily incorporate mouse 
shapes that you design with MKM II into your own programs.

Most operations in the MKM II dialog box have keyboard equivalents, to 
make editing quicker; it's worth the time to learn the key commands if you 
end up using the editor.


Using the Mouse Editor/Installer
--------------------------------

This section will explain how to use the MKM II desk accessory to install 
custom mouse cursors, and how to edit existing cursors or create your own.


   The Help Feature

  MKM II has an online help feature, with brief summaries of the most
  important points of operation, including a list of all the keyboard
  commands.  To access the help screens, click the Help button in the upper
  right corner, or type the Help key on your keyboard.  To advance through
  the help screens, click the left mouse button or type the spacebar.  To
  back up to a previous screen, press the right mouse button or type the
  Backspace key.  To exit immediately from the help screens, press both
  mouse buttons or type the Esc key. 


   Assigning Custom Cursors

  At the top of the MKM II dialog, next to the title, are eight selectable
  buttons with pictures of the eight standard system mouse cursors.  To
  assign a custom cursor to one of these eight, click the one you wish to
  assign so that it becomes selected (highlighted).  You can also type F1
  through F8 to select one of the standard cursors, or use the [ and ] keys
  to move forward and back.  As you change the selected standard cursor,
  notice that the editing grid changes to show the current shape for that
  cursor. 

  Click the "Load" button to load a custom cursor to replace the currently
  selected standard cursor.  MKM II will first ask you which type of file
  you wish to load (1 frame, animated, or AutoMouse), then present you with
  a file selector to let you locate and select the cursor file to load.  The
  MKM II archive includes several dozen cursor files, both animated and
  single- frame.  Animated cursors have a file extension of .MKM, while
  single- frame files use the .DAT extension. 


   Install/Remove

  If you choose to load an "AutoMouse" file (as described in the "Quick
  Start" section above), the cursors contained in it will be loaded AND
  installed, automatically.  When you manually load a single-frame or
  animated cursor, you'll need to click the "Install" button (or type I)
  before it will be assigned to the currently selected standard cursor.  If
  you've loaded an animated cursor for the first time, you will also need to
  turn animation on by clicking the bottom of the "Frame" box. 

  To deinstall one of the standard cursors (i.e.  return to the standard
  system shape), select the standard cursor and click the Remove button (or
  type X). 


   Global On/Off Switch

  You can quickly turn Mouse-Ka-Mania's cursor replacement features on 
  and off for ALL the standard cursors, by clicking the ON and OFF buttons at 
  the top right of the MKM dialog.


   Loading and Saving Mouse Cursors

  The "Load" and "Save" buttons (L and S on the keyboard) let you save your 
  edited cursors to disk, and load them back in.

  To save the current cursor, click the "Save" button.  An alert box will
  appear, asking if you want to save just the current frame or the entire
  animation sequence of 32 frames.  Choose which type of file you want to
  save, then use the file selector to locate the directory you wish to save
  into, and give the file a name.  When naming the file, you can omit the
  extension; Mouse-Ka-Mania II will automatically add the proper extension
  (.DAT for single-frame files, .MKM for animations) if you don't. 

  The "Load" button lets you load single-frame and animated cursor files,
  and also lets you load entire sets of cursors (called "AutoMouse" files;
  see below). 


                         EDITING TOOLS
                         =============

The Mouse-Ka-Mania II desk accessory has all the tools you need to edit
existing mice, or create new ones.  I'll go over some basic concepts
first, to help you use the editor effectively. 


What's In A Mouse?
------------------

A mouse cursor is composed of the "data" that defines the shape, the 
"mask" that keeps the image from blending in with the background, and 
the "hot spot" that determines where the active point of the cursor is. 
The mouse shape is defined within a square grid of 16 x 16 pixels.

The MKM II editor shows you magnified versions of both the data and the
mask, on two separate grids.  When you draw on one of the grids, it is
echoed on the other grid.  The hot spot is shown as a square with a darker
pattern on the data grid. 

In addition to setting and erasing individual dots on the grids,
Mouse-Ka-Mania II also has an assortment of editing tools to let you
perform more complex operations easily.


   Drawing and Erasing

  To draw on the grids, press the left mouse button.  To erase, press the
  right mouse button.  Drawing on the data grid is shown in solid black,
  while drawing on the mask grid uses a half-tone pattern.


   Setting the Hot Spot

  To set the hot spot (the place where "clicks" happen) hold the Control
  key while clicking the left mouse button in the data grid.


   Undo

  Don't panic if you make a change that doesn't turn out the way you
  hoped.  You can reverse your last action by clicking the Undo button or
  typing the Undo key on your keyboard. 


   Clearing the Data and Mask

  To completely erase the data or mask grids, click the buttons labeled
  "Clear Data" and/or "Clear Mask".  The keyboard equivalents for these
  buttons are Clr Home and Control-Clr Home, respectively. 


   Inverting the Data and Mask

  Clicking the "Invert Data" and "Invert Mask" buttons (or typing Insert
  or Control-Insert) causes all filled squares to become unfilled, and vice
  versa. 


   Mirroring the Data and Mask

  Clicking on the "Mirror Data" and "Mirror Mask" buttons (or typing M or 
  Control-M) causes the image to flip around on the horizontal axis.


   Rotate

  Clicking on the "Rotate" button (or typing R) causes both data and mask to 
  rotate 90 degrees clockwise.


   Scrolling the Data and Mask

  Above the "Rotate" button are four buttons with left, right, up, and down 
  arrows in them.  Clicking on any of these buttons causes both data and 
  mask grids to scroll one pixel in the direction selected.  These buttons
  correspond to the left, right, up, and down arrow keys on your keyboard.


   The Preview Box

  Above the scroll arrows is a box with the top half filled in solid black. 
  This is the "preview box"; when you move the mouse cursor into this box,
  it changes into the shape currently being edited, to let you see how it
  looks.  If animation is turned on for the current cursor, the animation
  will play while the mouse is inside the preview box. 


   Copy and Paste

  Mouse-Ka-Mania II has an internal "clipboard," to let you copy mouse
  shapes from one frame to another.  When you first open the editor, the
  Paste button is disabled because there is nothing on the clipboard.  When
  you click the Copy button (or type C) to copy the current shape to the
  clipboard, the Paste button becomes selectable.  Clicking the Paste button
  (or typing P) puts the clipboard contents onto the editing grids,
  replacing what's already there. 

  If you hold either Shift key while clicking the Paste button, the data and 
  mask parts of the mouse cursor on the clipboard will be swapped when 
  they are inserted.  If you hold Control while clicking Paste, only the data 
  will be pasted.  If you hold Alternate while clicking Paste, only the mask 
  will be pasted. 


   Setting the Colors of Data and Mask

  Immediately to the right of the scroll arrows is a box labeled "DATA
  COLOR," containing a number and up/down arrows.  This box is how you set
  the colors that will be used for the data and mask (that's right, custom
  mice can consist of more than one color!).  When you first open MKM II,
  the box will be titled DATA COLOR, and clicking the up/down arrows will
  change the color of the data portion of the mouse cursor.  To change the
  color used for the mask, click on the title to change it to MASK COLOR. 
  MKM II supports color indexes from 0 to 15. 

  You can also click directly on the color number itself to quickly set
  all the frames in an animation sequence to the same color. 


                      CREATING ANIMATED CURSORS
                      =========================

MKM II's unique ability to create and install animated mouse cursors is 
what sets it apart from other mouse shape editors.  Animated cursors can 
contain up to 32 "frames"; Mouse-Ka-Mania II "plays" the animation by 
looping through the frames at the speed you choose.

Creating an animation is a lot like putting on a pair of pants; you put your 
pants on one leg at a time, and you create an animation one frame at a 
time.


Moving To Another Frame
-----------------------

At the lower right of the MKM dialog (just above the Exit button) is a box 
titled CURRENT FRAME, containing a number surrounded by up/down 
arrows.  At the bottom of the box is a panel that says ANIMATION OFF 
(unless you've already loaded and installed an animated cursor).  This box 
controls many of the features related to animation.

Click on the title of this box to switch between CURRENT FRAME, # OF
FRAMES, and DELAY.  (Typing the Tab key does the same thing as clicking the
title.)  When the title of this box reads CURRENT FRAME, clicking on the
up/down arrows moves forward and backward through the frames of the
animation sequence.  The keyboard equivalents for the up and down arrows
in this box are F9 and F10. 


Selecting a Frame Directly
--------------------------

For a quicker way to move to a non-adjacent frame (for example, from frame
1 to frame 12), click directly on the number in the Frame box (or type F). 
A dialog box will appear, showing you all 32 frames in the current
animation and letting you select one by clicking.  This dialog is also a
handy way to view all the frames of a sequence at once, even if you don't
want to move to another frame. 


Copying From One Frame To Another
---------------------------------

You can copy from one frame to another by using the Copy and Paste 
buttons described above, but there's also a quick way to copy the mask 
and data from one frame to an adjacent frame -- hold Shift while clicking 
the up or down arrows in the Frame box.


Setting the Number of Active Frames
-----------------------------------

As mentioned already, animations can consist of up to 32 frames.  To set
the actual number of active frames in the animation, click the title of
the Frame box (or type the Tab key) until it reads # OF FRAMES, then use the
up/down arrows to adjust the number of frames in the sequence.  Animations
always start with frame 1, and end at the frame number you set here. 


Setting the Animation Speed (Delay)
-----------------------------------

To set how fast the animation "plays," click the title of the Frame box
(or type the Tab key) until it reads DELAY, then adjust the value with the
up/down arrows.  Smaller numbers mean faster speeds. 

Techie note: the delay value is the number of vertical blank interrupts to 
wait before showing the next frame.  If delay is set to zero, a new frame is 
shown in every vertical blank interrupt, approximately 60 or 70 times a
second (depending on the vertical refresh rate of your monitor).


Turning Animation On/Off
------------------------

You can turn animation on and off for the currently selected cursor by
clicking the bottom of the Frame box (or typing the O key).  The panel
will read either ANIMATION ON or ANIMATION OFF, showing you the current
state. 


                        AUTOMOUSE PROGRAMS
                        ==================

Mouse-Ka-Mania II has the ability to create small programs that run in 
your AUTO folder, installing custom mouse cursors without using the MKM 
II desk accessory, and using as little memory as possible.  AutoMouse 
programs can also be looked upon as sets of cursors, since the "Load" 
button allows you to load all the shapes contained in an AutoMouse file in 
one move.


Creating an AutoMouse Program
-----------------------------

Before clicking the button labeled AutoMouse, you should first create or 
load the set of mouse cursors you wish to use, click the Install button for 
each one, and turn animation on or off for each one.  OK, now you can click 
the AutoMouse button.  (Or type the letter A.)

A dialog appears, with panels containing the eight standard mouse cursors 
and other controls.  At the bottom of each panel is shown the first frame of 
the custom cursor you've assigned to that standard cursor.  There are radio 
buttons in each panel, letting you set whether the cursor is an animated 
cursor or a single frame.  MKM II makes an effort to preconfigure this 
dialog the way you'll probably want it, but if you want to change 
something, you can click on the boxes containing the standard cursor 
shapes to deselect them and remove them from the AutoMouse file, or 
change the states of the "1 Frame" and "Anim." buttons.

When everything is set the way you want it, click the Save button at the 
top of the AutoMouse dialog, or click Cancel to forget the whole deal.  If 
you click Save, a file selector appears to let you locate the place where you 
want to save the AutoMouse program and give it a name.


Installing an AutoMouse Program
-------------------------------

If you want an AutoMouse program to run at bootup and automatically 
install the shapes contained in it, place it in your AUTO folder and make 
sure it has a PRG extension when you name it.

Since you can also load AutoMouse programs or run them from the 
desktop (see below), you may also want to save them in another directory 
to use them as "cursor libraries."


Loading an AutoMouse Program with the MKM DA
--------------------------------------------

When you use MKM II's "Load" command to load an AutoMouse file, as in the
Quick Start section above, the entire set of cursors contained in the file
is installed automatically in one easy move.  There's no need to set
animation on or off for each one, or click the Install button. 


Running AutoMouse Programs from the Desktop
-------------------------------------------

If you launch one of these special AutoMouse programs from the desktop, 
Geneva, or HotWire, it searches for the Mouse-Ka-Mania II desk accessory 
in memory.  If it finds MKM II, the AutoMouse program simply copies its 
imbedded shapes into the desk accessory, automatically installs them, and 
quietly exits, taking up no additional memory.  This lets you install new 
sets of cursors without even opening the desk accessory.

Note: the desk accessory does need to be installed to take advantage of this 
feature.


                      EXPORTING SOURCE CODE
                      =====================

For programmers only!

Click the Export button to export a source code file, containing a C,
assembly language, or BASIC version of the current mouse cursor.  Only
single frames can be exported. 

The C file is a standard C header file, with an .H extension, defining the
mouse cursor as a simple array with a unique label based on the name of
the exported file.  The assembly language file is a standard 680x0 source
file, defining the cursor in a series of dc.w directives.  The BASIC file
is in GFA ASCII list format (.LST), and defines the mouse cursor as a
series of data statements.  The BASIC listing also includes a short
subroutine that calls the AES graf_mouse() function to set the mouse
cursor. 


              INSTALLING MOUSE CURSORS AUTOMATICALLY
              ======================================

The easiest way to install a set of mouse cursors is to put an AutoMouse
program in your AUTO folder, as described in the previous section.  But
the Mouse-Ka-Mania II desk accessory can also load a set of mouse cursors
automatically at bootup (or when loaded with MultiDesk Deluxe or Geneva). 
The desk accessory searches the directory where it lives for an AutoMouse
file named AUTOMOUS.PRG, and installs the shapes in this file if found. 
If AUTOMOUS.PRG is not found, the DA then searches its directory for the
following individual cursor files, with which to replace the eight
standard cursors:

  ARROW.MKM
  TEXTEDIT.MKM
  BUSYBEE.MKM
  POINTHND.MKM
  FLATHAND.MKM
  THINCROS.MKM
  THIKCROS.MKM
  OUTCROSS.MKM

Note that even though these files have an extension of MKM, they can be 
either animated or single-frame files.

