Crawly Crypt Collection 1

home *** CD-ROM | disk | FTP | other *** search

/ Crawly Crypt Collection 1 / crawlyvol1.bin / utility / misc / mkm21 / mkm_ii.txt < prev

Wrap

Text File | 1994-03-10 | 29KB | 673 lines

------------------------- 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.1 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. COMPATIBILITY ISSUES ==================== Mouse Accelerators ------------------ If the mouse cursor "creeps" to the right when you install an animated cursor for the GEM arrow, it's because you're using a mouse accelerator utility that does not allow single-pixel movements. You can avoid this problem by configuring the mouse accelerator to a slightly less sensitive setting (if possible). Mouse-Ka-Mania II detects the presence of Warp 9 and has special code to get around this problem when Warp 9's mouse accelerator is being used, so you'll never see "creeping" no matter how sensitive a setting you use. The same applies to the popular SilkMouse mouse accelerator. CodeKeys -------- If you use CodeKeys, the keyboard/mouse macro scripting program from CodeHead Technologies, and animated cursors cause your macros to abort, you can fix this by locking your CodeKeys macros. See the CodeKeys documentation for more info about locking macros. Do Not Squish, Spindle, or Mutilate ----------------------------------- If you use a compression program like Squish or PFXPAK on an AutoMouse program, it will work if the program is executed in a normal fashion (from the AUTO folder or desktop). However, attempting to load a compressed AutoMouse file into the MKM II desk accessory with the 'Load' command will cause a crash. AutoMouse programs are so small that you won't gain much by compressing them anyway, so be safe and don't! VERSION HISTORY =============== Version 2.0 ----------- After a long interment, Mouse-Ka-Mania rises from the dead to walk the earth and wreak havoc in the lives of Atari users. Version 2.1 ----------- Fixes a problem that could cause crashes when loading certain types of AutoMouse files into the desk accessory.