Loadstar 236/236.d81/t.dbdocs0

Text File | 2004-01-01 | 8.4 KB | 385 lines

u
           D O T B A S I C
            (version 1.01)

              Program by
      Dave Moorman and Lee Novak
         Text by Dave Moorman


    The more I use DotBASIC, the more
power I find. Most of that power is
the work of Lee Novak, who took the
ideas of a mouse driver module
and a screen effects toolbox and
merged them into to the legendary Mr.
Mouse.

    DotBASIC begins with Mr.Mouse, but
adds incredible features of its own --
not the least of which being Event
Driven programming.

    The Dot Commands consist of a dot
(period) and two characters. They are
two characters long for two reasons.
Two is better than one, and two
characters correspond in memory to the
two byte jump addresses they refer to.
The method is quick! Just look up the
name in one table, then use the index
to point to the address in another
matching table.

    One feature you have to remember
is that when using a Dot Command after
a THEN, put a colon in the way.

        IF A=5 THEN:.RK,40960


    Here is the full documentation for
DotBASIC Commands.


  START: SYS 4608,med page
  ------------------------

    This command is already done for
your in the template program (the one
given your PROGNAME.DOT when you begin
programming. MED PAGE is the location
where the .MED file was bloaded by the
boot program -- normally page 224. You
can modify the boot and load the .MED
file anywhere you have 18 free pages.
Just be sure this command points to
your file.


  STOP: SYS 4611
  --------------

    This is exactly the same as the
.OF command below. It is here, just in
case.


DO-LOOPING
----------

    Probably the single most powerful
feature of DotBASIC is Do-Looping. I
borrowed the code from Lothar Englisch
who explained the technique in the
1984 Abacus book, [Advanced Machine]
[Language Programming for the]
[Commodre 64]. It uses ML methods that
cannot be easily adapted to our
favorite [SYS ADD, param] module
structure -- hence the new command
names.

    The program will loop between the
.DO and the terminal comparison --
either .UN or .WH, without having to
hunt down line numbers as is the case
with GOTO.


  DO: .DO
  -------

    Begins the Do-Loop. Do-Loops can
be nested indefinitely (up to the
capacity of the processor stack).


  UNTIL: .UN comparison
  ---------------------

    Note that there is [no comma]
between the command and the parameter.
This is a remnant of Lothar's code and
I couldn't fix it.

    COMPARISON can be anything that
has a value of either 0 or not 0.

       A>5, (Q>2 and Q<7), RG%

 I have learned to use variables as
Boolean controls -- True or False --
with False being 0 and True being not
0. So you will see in line 100:

      100 .DO:.EE:.WB:.UN E%:.OF

 were E% is 0 until acted upon by
other code.

    UNTIL loops until the comparison
is True.


  WHILE: .WH comparison
  ---------------------

    WHILE loops while the comparison
is True.


  DotBASIC OFF: .OF
  -----------------

    This command turns off DotBASIC
and puts all its toys away. The Dot
Commands do not work after .OF has
been executed. If you are putting
STOPs in your code while debugging,
include .OF first.

            4982 .OF:STOP


  EVENT ENABLE: .EE
  -----------------

    This is used in the Main Event
Driver Loop -- line 100 -- and you
will probably never need to use it in
your own code. When an Event happens
and the Event Handling code is called,
the Event Driver is disabled (which
keeps other Events from getting in the
way). When the Event Handler is
finished and RETURNs to the Main Loop,
.EE is there to re-enable the Event
Driver.


  EVENT DISABLE: .ED
  ------------------

    Allows you to disable the Event
Driver. Useful when you want to do
everything by hand, rather than use
the Main Event Driver Loop as given.
Also, you may have some set-up code
that happens after DotBASIC is started
and the Main Event Driver Loop. Use
.ED so your set-up code will not be
interrupted by an Event.


  WAIT BACK ARROW: .WB
  --------------------

    This command was also created for
the Main Event Driver Loop. .WB
watches the <BACK ARROW> key, and when
the key is depressed, E% becomes -1.
This then ends the loop.


  YES/NO: .YN,x,y,u,h
  -------------------

    Putting a simple Yes/No response
in a dialog box can be a pain. But not
anymore! Just use this command. X and
Y are the screen coordinates. U is the
unhighlighted (and box) color and H is
the highlighted color.

    Use the add-on values shown in the
BLOCK command to make the Yes and No
change when highlighted or not. I find
that +208 to each color gives a neat
unreversed-when-pointed-to effect.

    The user's response is returned in
I% -- No = 0, Yes = -1.


  ARE YOU SURE: .RU,u,h
  ---------------------

    This puts a nice dialog box in the
center of the screen in the U color
that asks, appropriately enough, Are
Your Sure? The YES/NO command and the
u and h colors work the same as above.


STRING DATA
-----------

    The RACK command (covered later in
these docs) is powerful. You can BLOAD
an Edstar text file (with a 0 byte at
the end), do a RACK, and have the data
become a virtual string array. The
data can be anywhere in memory --
under ROM or I/O -- and not occupy
precious BASIC memory. With RACK
INDEX, every string line can be
accessed.

    This was too good to leave alone.
So we added the String Data commands
that allow you to put strings into
memory for RACKing and INDEXing.


  LOCATE STRING DATA: .$L,location
  --------------------------------

    This must be done first, telling
DotBASIC where in memory your string
data will start.


  PUT STRING DATA: .$P,string
  ---------------------------

    This puts strings into the string
data area, beginning at the location
specified with .$L. Each string is
ended with a 0 byte. The next string
is put over the previous 0 byte. When
finished, the data can be RACKed and
INDEXed like an Edstar file.



  INSTRING: .$I,search$,target$
  -----------------------------


    Ever wanted to find out if one
string of characters is contained in
another string. You can certainly use
a FOR-NEXT loop with MID$. But
INSTRING does it at lightning ML
speed. If found, the position of the
first character of the search string
contained in the target string is
returned in I%. If not found, I%=0.


  WAIT KEY: .WK
  -------------

    Does the same as:

        10 GETZ$:IFZ$=""THEN10
        20 I%=ASC(Z$)


  IRQ SUSPEND: .QS
  ----------------

    One should disable Sprites and IRQ
interrupts during disk access. .QS
does this for you, turning off the
mouse and arrow.


  IRQ RESTORE: .QR
  ----------------

    Restores the mouse and arrow after
a .QS and disk access.


  SIGNED INTEGER TO +FLOATING PT:
  .IU,value
  -------------------------------

    Don't you hate it when a two-byte
positive value, such as FRE(0) goes
negative when reported to BASIC. A
number of Mr.Mouse commands return
information in signed integers that
should be unsigned. So we added this
command. VALUE is any value, -32768 to
32768. The two-byte positive value is
returned in FP.


  POKE TWO BYTES: .P2,location,value
  ----------------------------------

    You can now poke a two-byte value
into two bytes. For example, if you
want to put the REGION DATA for your
own region work at 50123, all you need
to do is

             .p2,MV,50123

 This replaces

      POKE MV,203:POKE MV+1,195


  GET TWO BYTE VALUE: .G2,location
  --------------------------------

    A two-byte PEEK. .G2,MV returns
PEEK(MV)+PEEK(MV+1)*256 in FP.


  POKE ONE BYTE: .P1,location,byte
  --------------------------------

    Talk about not necessary!


  GET ONE BYTE: .G1,location
  --------------------------

    This is a little more useful
because the result is returned in I%.


  TEXT COLOR:        .TX,color
  BACKGROUND COLOR:  .BG,color
  BORDER COLOR:      .BR,color
  ----------------------------

    The three commands BASIC 2.0 left
out when ported to the C-64 from
monochrome PET. I have added [one]
more feature for this release:

    For .TX,color add 128 to the color
code for reverse text. As I was going
through the Cookbook docs, I realized
it was stupid to have to

        .BX,x1,x2,y1,y2,160,7
        .TX,7
   >>>> PRINT"<rev>";
        .PC,y1+1,"This Is REVERSED"

every time one does a BOX. The code
now will be

        .BX,x1,x2,y1,y2,160,7
        .TX,7 + 128
        .PC,y1+1,"This IS Reversed"

Now, that was easier, wasn't it?


    The next three docs cover the
Mr.Mouse commands and related Dot
Commands. Don't forget to print out
the DB Command Sheet for a three page
reminder of the power of DotBASIC.

 DMM