Loadstar 236/236.d81/t.dbdocs1

Text File | 2004-01-01 | 12.2 KB | 479 lines

u
        DOTBASIC DOCUMENTATION
                Part 2

              Program by
      Dave Moorman and Lee Novak
          Text by Lee Novak


    Here is the Mr. Mouse portion of
the documentation for DotBASIC. I have
edited the following to refer to
DotBASIC commands. Otherwise, Lee sees
all and tells all.

 DMM


    I am pleased to finally present
the reworking of one of LOADSTAR's
most popular toolboxes. I'd like to
thank Jeff Jones for his help in this
project. Without it, DotBASIC would
have been quite different. He stopped
me from making a couple of BIG
mistakes, and even some of his ideas
are among this mess of code.

[NOTE:] I do not know of anyone who
did more to make BASIC programming
easy and elegant than Jeff Jones. He
introduced the earliest Toolbox back
on LOADSTAR 91, and proceeded to
improve it until Lee got into the act
with Mr.Mouse. DMM


    Programs written with DotBASIC
(DB) automatically support both a
mouse in port 1 and a joystick in port
2. The FIRE button on the joystick is
the same as the left mouse button. For
joystick users, any key can be defined
to replace the missing right mouse
button. The middle button (on CMD's
SmartMouse) will double the mouse's
speed.

    Lee has included many internal
variables and controls that can be
accessed with POKE MV+offset. The
variable MV is automatically assigned
when DotBASIC is initiated.


    Let's go over the features
included in DotBASIC. First off, the
keyboard can mimic the mouse buttons.

   Related Variables:     (& defaults)

  MV+14  Right Keycode        (F7 = 3)

    MV+14 holds the keyboard
equivalent to the right mouse button.
The spacebar serves as the left button
-- people expect this. The right
button is defined as F7, but you could
change it if you've assigned a
function to the right mouse button and
would like to use F7 (and F8) as
hotkeys instead.

    Note that MV+14 is not an ASCII
code. "Keycodes" are generated by the
SCNKEY routine during the interrupt.
They can be determined with this
one-line program:

   10 print peek(203):goto 10

    When you RUN it, hold down the key
you want to designate as a button and
note the number showing. Be aware that
keycodes are not affected by the
special (SHIFT) keys, and these
special keys don't have keycodes - so
they can't be used as mouse buttons.

  MV+18  Keyboard Enable (default 129)

         +128 = Return can click
         +64  = Space can click
         +32  = Commodore can click.
         +1   = CRSR keys move arrow

    Even the CRSR keys can control the
arrow pointer around the screen. This
makes it especially easy to add
"keyboard support" to your programs
without having to think about it. By
default, the RETURN key serves as the
left mouse button.

     With a POKE, you could enable
the COMMODORE key to also serve as
the left mouse button. This would be
useful for any "click and drag"
situations within your program, only
because the Commodore key can be read
independently of the CRSR keys. It is
awkward to use, but it works. RETURN
or SPACE can be used to "click" the
rest of the time. It's more natural.


    You can change the appearance of
the mouse arrow with

  MV+17  Twin Flag    (default is 128)

    A Twin Flag setting of 128 (or
higher) will cause sprite 1 to be
enabled as a black shadow arrow. After
that, it is the interrupt's job to
ensure the shadow arrow follows the
other sprite. The Twin Flag may be set
to these values:

     0 = Single sprite only
   128 = Dual sprite, shadow @ x+2,y+1
   192 = Dual sprite, perfect sync

    Although 192 would cause the
shadow sprite to be directly under the
pointer sprite, and thus unseen, there
ARE other uses for this feature. The
sprites don't have to share the same
shape, you know.


  ASK BASIC: .MA
  --------------

    This crucial command is the only
way to get feedback from DotBASIC
outside the Main Event Driver Loop
(line 100 on the template program).
Feedback is deposited in integer
variables. Here's the wealth of
information you will get:

   Mouse position information

   PX%  Pixel-X location (0-319)
   PY%  Pixel-Y location (0-199)
   CX%  Cell-X location  (0-39)
   CY%  Cell-Y location  (0-24)

   Mouse button information

   L1%  Left button    (0=up, 1=down)
   R1%  Right button   (0=up, 1=down)
   L2%  New left push  (0=no, 1=yes)
   R2%  New right push (0=no, 1=yes)

     While L1% and R1% merely return
the state of the buttons, L2% and R2%
tell you if the press is NEW. This is
useful for clicking on things. Here is
a sure-fire way to sense a new click:

 100 .MA
 101 IF(L1% AND L2%)=0 THEN 100
 102 <<CLICK HAPPENED>>

[NOTE:] Use the .DO loop:

    .DO:.MA:.UN L2%

 This works splendidly. DMM


    There are also other times when
you want to do something when the
button is pressed, but not continually
as the user holds the button down and
scoots across the screen.

    Internally, new button presses are
nulled when the button is lifted or
the .MA routine is called.


   Text screen information

   SC%  Screen Code under mouse
   CC%  Color Code under mouse
   PP%  Pointer Position of mouse

    The color data is stripped of its
upper (garbage) nybble. The pointer
position is the RAM location of the
screen cell right under the mouse.
Since PP% is an integer, values above
32767 will be negative.

[NOTE:] This won't be a problem is you
use the default screen at $0400
(1024). But should you get brave, use
.IU,PP% to put the full, positive
value in FP!  DMM


   Region information

   RG%  Region # mouse is over (0-64)
   CR%  Region # being clicked (0-64)

    A "region" is an area of the
screen that you can define by its
x1,x2,y1,y2 limits. (The Event Regions
you define with VDOT are these very
regions!) RG% will be zero unless the
mouse pointer is currently on top of
an ACTIVE region. CR% will be zero
unless the user is currently
left-clicking on a particular region.
In the case of overlapping regions,
the higher number is returned.

    The "freshness" of all mouse
feedback depends on how often you are
able to call the ASK routine, and how
quickly your program can respond to
the data.


  PRINT AT: .P@,x,y,string
  ------------------------

    This prints a string as you'd
expect - with one exception. To aid in
readying lists and menus, any F7's
embedded in the string (inside quote
mode) will result in a tab back to the
X coordinate and a cursor down.


  DEFINE REGION:
  .RD,region #,x1,x2,y1,y2
  ------------------------

    Any area of the screen can be
defined as a "region". You specify the
region number (1-64) and its cellular
limits. By using regions, you can
easily tell if the mouse is over an
icon, box, or whatever. You can
re-define a region on the fly and
indefinitely.

[NOTE:] Remember, Event Regions are
regions, too. Define Regions only in
Event Handling routines or when the
Event Driver has been disabled. Also,
it is a good idea use a different
Region Data Zone for your own regions.
One place that is handy (unless you
are using sprites) is page 35.

 POKE MV+1,34

 When the code returns to the Main
Event Driver Loop, the Event
Region Data is restored automatically.
(DMM)


   Related variables:     (& defaults)

  MV+0  Region Data Zone: LB     (0)
  MV+1  Region Data Zone: HB     (4)
  MV+2  Number of Active Regions (0)

    Defined regions are not "seen" by
the mouse unless you mark them as
ACTIVE, by placing a value into MV+2.
For example, if this number is 7, then
regions 1-7 are active. Each time you
define a region, that region number is
automatically placed into MV+2 for
your convenience. You may change this
number at will.

    Region data can be placed almost
anywhere in memory, the exception
being under the ROMS or I/O. As
mentioned in the NOTE above, if you
are defining and using run-time
regions, you should first set the
Region Data Zone with POKEs to MV+1
and MV+0 before defining regions. It's
your job to ensure this area is safe
from BASIC and your other data.

[NOTE:] As I was doing the final edit
on this text, I tried an experiment. I
POKEd MV+2 with a 0 in line 99 -- just
before the Main Event Driver Loop. The
Event Driver was very uneventful!
Nothing happened. No roll-over, no
clicks. Dead!

 So, If you want to disable certain
Event Regions, organize them so the
ones you want to disable are higher
numbered than the ones you want
active. Then reduce the value in MV+2.
But remember, you [cannot] add Event
Regions on the fly. You will get a
Syntax Error. DMM


  CAGE MOUSE: .MC,x1,x2,y1,y2
  ---------------------------

    This command confines the mouse
pointer's movement within an area. It
is almost not even needed, since menus
automatically alter the cage and the
.QR command ensures you start out
with a full-screen cage.

    Check out QUICKSMITH (on LS #164)
to see a use I have found for CAGE.
When you are using the slider bar, the
mouse is caged within the range of
movement the bar allows. On more
expensive computers, the mouse can
"slip" off the slider bar and cause
confusion.


  POSITION MOUSE: MP,x,y
  ----------------------

    Use this command to place the
mouse at any cellular X,Y location. If
you attempt to place the mouse outside
of its "cage", it will be snapped back
inside instantly.


  PAUSE: .@Z,jiffies
  ------------------

    This routine waits for the
specified number of mouse interrupts
to pass before returning control to
you. The wait is (usually) measured in
sixtieths of a second, and the value
cannot exceed 255.


  PRINT CENTER: .PC,y,string
  --------------------------

    This routine prints your string
(up to 40 characters) centered on any
line y (0-24). Don't use F7's in these
strings as you probably won't get the
effect you were looking for.


  BLOCK: .BX,x1,x2,y1,y2,sc,color
  -------------------------------

    The BLOCK command is able to
perform a variety of tasks, based on
the parameters you feed it. The last
two parameters specify what to do
within the boundaries:

  BLOCK: To fill an area with a
    character, just specify its screen
    code (0-254) and the color you
    want it to be (0-15).

  PAINT: Using 255 for a screen code
    causes the routine to only color
    the area, leaving screen RAM
    intact.

  SHADE: Using 255 for a color code
    causes all of the colors in the
    area to be assigned a darker shade
    than each currently has. Screen
    RAM is not affected.

  REVERSE, UN-REVERSE, and FLIP: Add
    128 to the color code to invoke
    reverse, 64 for un-reverse, and
    192 for flip. Color RAM will not
    be affected unless you add an
    additional 16 to the values above.

  FRAME: Adding 32 to the color code
    will draw a frame (like BOX below)
    that ignores the center area
    automatically.

  BOX: Adding 16 to the color code
    results in a box made up of nine
    specific characters. The defaults
    work well with either case font.
    They can be changed for use with
    custom fonts that have their
    box-making characters elsewhere.

    BOX refuses to use screen code 0
    in what it draws. This is so you
    can set MV+41 (the screen code
    used to draw the interior of
    boxes) to zero. The effect is that
    BOX now behaves like FRAME,
    leaving the center alone.


  AFFECT REGION: .RA,region #,sc,color
  ------------------------------------

    This command is just like BLOCK.
But instead of specifying x1,x2,y1,y2
parameters, you indicate which region
you want to affect.

    AFFECT is most often used in
causing visible changes to a region
when it is clicked on. It can also
help in setting up screens. Event
Regions can be affected at will!


  SCREEN STASH:   .SS,page
  SCREEN RESTORE: .SR,page
  ------------------------

    SCREEN STASH will store the text
screen and color map anywhere in
memory, even under ROM and I/O. 8
consecutive pages (2048 bytes or 2K)
are needed to save both areas. The
border and background colors are also
saved.

    SCREEN RESTORE displays a stashed
screen from anywhere in memory. The
border and background colors are also
restored.

[TECHNICAL NOTE:] The stash/restore
routines copy 1002 bytes each of the
screen and color map. STASH will put
the border and background colors into
locations $d800+1000 and $d800+1001
before doing the memory transfer.
After RESTOREing, the colors are
brought back from those locations. The
two bytes after the end of the screen
are stashed and restored also, but
they have no significance.


    We are just getting started. More
fun to come in Part 2!