============================================================================
               TextMouse: Graphics Mouse Cursor in Text Mode
============================================================================
                         by Plasma / Jon Petrosky               [07-08-2002]
                             www.phatcode.net

                           Freeware/Open Source


============================================================================
Contents
============================================================================

1. Introduction
2. Using TextMouse
3. Function Reference
4. Other Stuff
5. Closing Words


============================================================================
1. Introduction
============================================================================

What is this?
-------------
TextMouse is just a little library for QuickBASIC that allows you to use a
graphics mouse cursor in all text modes. It also has a few other "goodies",
like the ability to load custom mouse cursors and fonts and enable all the
background colors.

You are free to use the TextMouse library or any code from it in your own
programs; just remember to give credit where it is due.

Run the demo!
-------------
If you haven't already done so, run the demo! (DEMO\DEMO.EXE) You'll see
just exactly what you can do with TextMouse. (If you're using Windows, make
sure to run it full-screen.)

Files Included
--------------
TXTMOUSE.BI          TextMouse include file
TXTMOUSE.LIB         Standard library version of TextMouse for compiling
TXTMOUSE.QLB         QuickLibrary version of TextMouse for the QB IDE
TXTMOUSE.TXT         This document
DEMO\BINGO_8.FNT     Custom 8x8 font for the demo
DEMO\DEMO.BAS        Source code for the demo
DEMO\DEMO.EXE        Compiled version of the demo
DEMO\HOURGLAS.CUR    Custom mouse cursor for the demo
DEMO\LITE_16.FNT     Custom 8x16 font for the demo
SOURCE\MAKECUR.BAS   Program to create custom mouse cursors (quick-n-dirty!)
SOURCE\TXTMOUSE.BAS  Source code to the entire TextMouse library

Features
--------
* Supports 40x25, 40x43, 40x50, 80x25, 80x43, and 80x50 text modes.
* Supports custom mouse cursors, with variable "hot spots"
* Supports custom fonts (8x8 and 8x16).
* Reprograms x25 and x50 text modes to use 8x16 character spacing, instead
  of 9x16 character spacing. This eliminates cursor "stretching".
* Enables background colors 8-15.
* Mouse cursor is 100% flicker-free, achieved by using paging and cursor
  character flipping.

How does it work?
-----------------
TextMouse disables the lousy block text mouse cursor and instead uses the
ability to redefine text characters to generate a graphics mouse cursor "on
the fly".

Requirements
------------
* Microsoft-compatible mouse driver
* VGA
* Program must be run full-screen. (Windows does not allow custom fonts in a
  windowed DOS box, so if you run the program in a window you will just see
  garbage for the mouse cursor).


============================================================================
2. Using TextMouse
============================================================================

Setup
-----
First, you'll have to load the TextMouse library when you start QB. You can
do this by starting QuickBASIC typing:

QB /L TXTMOUSE.QLB

Next, you need to include the file TXTMOUSE.BI by adding this line at the
top of your code:

'$INCLUDE: 'TXTMOUSE.BI'

Usage
-----
Here's the a basic guideline for using TextMouse:

1. Use Text.SetMode first to set the mode you want and specify which
   characters you want to reserve for the mouse cursor. For example:

   Text.SetMode 80, 25, 1

2. Load a font using Text.FontLoad (even if you do not want a custom font,
   you must use Text.FontLoad to load the BIOS font into the buffer!)

   To load a custom font:
   Text.FontLoad "FONT.FNT"

   To load the BIOS font:
   Text.FontLoad ""

3. Apply the entire font:

   Text.FontApply 0, 255

4. Check to make sure a mouse is present by using Text.MouseInit:

   IF NOT Text.MouseInit THEN
     PRINT "No mouse!"
     END
   END IF

5. In the main loop(s) of your program, you must first get the mouse stats
   by calling Text.MouseStatus. (This updates the internal variables that
   are needed by Text.Update to draw the cursor on the screen.) For example:

   Text.MouseStats x, y, lb, mb, rb

6. Now you can update the display by using either PRINT or Text.Print. Note
   that TextMouse requires you to reserve one text page (usually 0) for the
   display, and write to another page (usually 1) instead.

   If you are using PRINT, you need to be sure and set page 1 to the active
   page and page 0 to the visual page. For example:

   SCREEN 0,,1,0
   COLOR 15, 1
   LOCATE 12, 5
   PRINT "Hello World!"

   If you are using Text.Print, you can just specify page 1 as the page you
   want to write to. For example:

   Text.Print 1, 12, 5, "Hello World!", 15, 1

7. When you want to update the screen, just call Text.Update, specifying
   the active and visual pages. For example:

   Text.Update 1,0

   This takes screen 1, applies the mouse cursor to it, and then copies it
   to the visible page. This method is used in order to help eliminate
   flicker.

8. Now you can loop back around and get the mouse stats, write to the active
   text page, and update the screen again. Repeat as necessary. ;)

9. Before you end your program, you should use Text.Restore to restore the
   standard text mode that was in effect before Text.SetMode was called.

If you are still confused on how to use Text.Mouse, take a look at the
source code for the demo. (DEMO\DEMO.BAS)


============================================================================
3. Function Reference
============================================================================

Main
----

-- SUB Text.SetMode --------------------------------------------------------

Prototype: DECLARE SUB Text.SetMode (Cols, Rows)

Description: Sets the specified text mode, and then changes the font width
             from 9 to 8 (in x25 and x50 modes). Also enables background
             colors 8 to 15.

Parameters: Cols  =  Columns to use; can be 40 or 80
            Rows  =  Rows to use; can be 25, 43, or 50


-- SUB Text.Cls ------------------------------------------------------------

Prototype: DECLARE SUB SUB Text.Cls (Page, ForeColr, BackColr)

Description: Clears a text page using the specified background color.

Parameters: Page  =  Text page to clear, in the range of:
                     0 to 7 for 40x25, 40x43, and 80x25 modes
                     0 to 3 for 40x50, 80x43, and 80x50 modes
        ForeColr  =  Foreground color to use (0 to 15)
        BackColr  =  Background color to use (0 to 15)


-- SUB Text.Print ----------------------------------------------------------

Prototype: DECLARE SUB Text.Print (Page, Row, Col, Text$, ForeColr, _
           BackColr)

Description: "Prints" text on the specified page at (Row, Col) using the
             specified foreground and background colors.

Parameters: Page  =  Text page to use, in the range of:
                      0 to 7 for 40x25, 40x43, and 80x25 modes
                      0 to 3 for 40x50, 80x43, and 80x50 modes
             Row  =  Row to start on (1 to 25, 43, or 50)
             Col  =  Column to start on (1 to 40 or 80)
           Text$  =  Text to print (all characters are literal!)
        ForeColr  =  Foreground color to use (0 to 15)
        BackColr  =  Background color to use (0 to 15)


-- SUB Text.Update ---------------------------------------------------------

Prototype: DECLARE SUB Text.Update (WorkPage, VisPage)

Description: Applies the mouse cursor to the text page WorkPage and then
             copies the page to the text page VisPage. (The original text
             page WorkPage remains unchanged when the sub is finished,
             however.)

Parameters: WorkPage  =  Hidden page where updating takes place
             VisPage  =  Visible page where mouse cursor is displayed


-- SUB Text.Restore --------------------------------------------------------

Prototype: DECLARE SUB Text.Restore ()

Description: Restores the screen mode to what it was prior to calling
             Text.SetMode. (This sub is needed in order to reset the screen
             font to 9x16)


Mouse
-----

-- FUNCTION Text.MouseInit -------------------------------------------------

Prototype: DECLARE FUNCTION Text.MouseInit (CursorCharStart)
 
Description: Checks to make sure that a mouse is present and reserves 18
             ASCII characters for the mouse cursor.

Parameters: CursorCharStart = ASCII code of the first character to reserve
            for the mouse cursor. (18 chars are required, so if you specify
            1 as the start char, then chars 1-18 will be used for the
            cursor.)                   

Returns:  0  =  Microsoft-compatible mouse not found
         -1  =  Mouse found and initialized


-- SUB Text.MouseLoad ------------------------------------------------------

Prototype: DECLARE SUB Text.MouseLoad (Filename$)

Description: Loads either the standard  mouse cursor, or a custom cursor
             from disk.

Parameters:  Filename$  =  Filename of a custom cursor. If filename
                           is null, does not exist, or is an invalid
                           format, the standard arrow will be loaded.


-- SUB Text.MouseStatus ----------------------------------------------------

Prototype: DECLARE SUB Text.MouseStatus (MouseX, MouseY, LeftButton, _
           MiddleButton, RightButton)

Description: Gets the mouse status and returns it using the parameters.

Parameters:        MouseX  =  Mouse x coordinate
(values            MouseY  =  Mouse y coordinate
 returned)     LeftButton  = -1 if button is pressed, otherwise 0
             MiddleButton  = -1 if button is pressed, otherwise 0
              RightButton  = -1 if button is pressed, otherwise 0


-- SUB Text.MouseRange -----------------------------------------------------

Prototype: DECLARE SUB Text.MouseRange (x1, y1, x2, y2)

Description: Sets the mouse range. The mouse cursor will not be able to move
             outside this range.

Parameters:  x1  =  Starting x coordinate
             y1  =  Starting y coordinate
             x2  =  Ending x coordinate
             y2  =  Ending y coordinate


-- SUB Text.MouseHide ------------------------------------------------------

Prototype: DECLARE SUB Text.MouseHide ()

Description: Disables the mouse cursor.


-- SUB Text.MouseShow ------------------------------------------------------

Prototype: DECLARE SUB Text.MouseShow ()

Description: Enables the mouse cursor.


Font
----

-- SUB Text.FontLoad -------------------------------------------------------

Prototype: DECLARE SUB Text.FontLoad (Filename$)

Description: Loads either the default BIOS font, or a custom font from disk.

Parameters:  Filename$  =  Filename of custom disk font. If filename
                           is null, does not exist, or is an invalid
                           format, the BIOS font will be loaded.

Notes: For 40x25 and 80x25 modes, the file must be an 8x16 font. For
       all other modes, the file must be an 8x8 font.


-- SUB Text.FontApply ------------------------------------------------------

Prototype: DECLARE SUB Text.FontApply (StartChar, EndChar)

Description: Updates the DOS font with the characters (StartChar to EndChar)
             in the currently loaded font.

Parameters: StartChar  =  Starting character to update (0 to 255)
              EndChar  =  Ending character to update (0 to 255)


-- FUNCTION Text.FontGetChar$ ----------------------------------------------

Prototype: DECLARE FUNCTION Text.FontGetChar$ (Char)
 
Description: Returns the bit image of the specified character in the
             currently loaded font.

Returns:  8 or 16-byte string containing character bit image


-- SUB Text.FontSetChar ----------------------------------------------------

Prototype: DECLARE SUB Text.FontSetChar (Char, BitImage$)

Description: Updates the bit image of the specified character in the
             currently loaded font.

Parameters:       Char  =  Character to update (0 to 255)
             BitImage$  =  8 or 16-byte bit image to use


============================================================================
4. Other Stuff
============================================================================

Custom Font/Cursor File Formats
-------------------------------

8x16 font: Each pixel is one bit. (Making each row of pixels in a character
           one byte, and 16 bytes for each character.) The characters are in
           order from 0-255. The total file size should be exactly 4096
           bytes. (256 characters x 16 bytes for each character.)

8x8 font:  Each pixel is one bit. (Making each row of pixels in a character
           one byte, and 8 bytes for each character.) The characters are in
           order from 0-255. The total file size should be exactly 2048
           bytes. (256 characters x 8 bytes for each character.)

Mouse cursor: The mouse cursor is 16x16. Each pixel is two bits (can be
              0-3). 0 = transparent, 1 = background color, 2 = foreground
              color, and 3 = inverse. So each row is 4 bytes:
              (16 pixels x 2 bits = 32 bits = 4 bytes)
              and the entire cursor is 64 bytes:
              (4 bytes x 16 rows = 64 bytes)
              
              There may also be an additional byte which determines the
              hotspot location (X low 4 bits, Y high 4 bits). If not
              included, the hotspot is assumed to be (0,0), and the total
              file size should be 64 bytes. If the hotspot byte is included,
              the total file size should be 65 bytes.

Making Custom Cursors
---------------------
You can use the included program (SOURCE\MAKECUR.BAS) to generate custom
mouse cursors. Just edit the source code to change the mouse image, hotspot,
and output filename, and then run the program. This is NOT a complete cursor
editor by any means; it's simply a quick program to generate cursors. In the
next version of TextMouse I will have a real cursor editor :)

Making Custom Fonts
-------------------
Sorry, no font editor is included. However, the font format that TextMouse
uses is identical to that of many other DOS font editors. (In fact, you can
even use 8x8 Impulse Tracker fonts with TextMouse...) I'll have a font
editor in the next version, also, if you can't find an editor that you like.

FAQ
---
Q: If the mouse cursor is only 16x16, why does it use 18 characters?!
   Shouldn't it only take 2 characters (with an 8x16) or 4 characters (with
   an 8x8 font)?

A: First of all, you have to consider the possibility that the mouse cursor
   will not be sitting exactly on 2 or 4 characters. It could be halfway
   between. If you're using 8x8 characters, a 3x3 character block needs to
   be used to make sure that there is always room for the cursor. This takes
   up 9 characters. To eliminate flicker that may occur when the font is
   updated before the screen is updated, a second set of 9 characters must
   be used. TextMouse switches back and forth between these two 9-character
   sets. This is where the 18 characters go. :)

Q: Why doesn't the mouse cursor update automatically, like other mouse
   libraries?

A: TextMouse is NOT a mouse driver. Other mouse libraries simply use the
   mouse driver to draw the cursor. (The mouse driver can update the cursor
   automatically.) However, the mouse driver can't do what TextMouse does,
   so TextMouse does not use the mouse driver to draw the cursor. :P

Q: Why can't TextMouse detect when I press the middle mouse button?

A: Your mouse driver has to support this function. It seems that most
   Microsoft mouse drivers do not support this, while Logitech, Mouse
   Systems, and Genius drivers do.

Q: This is ghetto. Who uses text mode anyway?

A: Who uses QuickBASIC anyway?


============================================================================
5. Closing Words
============================================================================

Future Versions
---------------
In future version(s) I plan to add:

* A mouse cursor editor
* A 8x8 and 8x16 font editor
* Possibly the ability to update the mouse cursor automatically
  (no guarantees here!)
* Something else? Email me if you want something else added!


Signing off,
Plasma
-------------------
plasma@phatcode.net


[End of File - Last modified: July 8, 2002 - 12:22 pm]
