Loadstar 236/236.d81/t.dbdocs4

Text File | 2004-01-01 | 13.4 KB | 515 lines

u
        DOTBASIC DOCUMENTATION
                Part 5

   And now the exciting conclusion!


  GET DIRECTORY:
  .B$,"$:*",dv,loc,# filenames
  ----------------------------

    This will read the disk directory
from device DV. The directory can be
placed anywhere, even under I/O.
MM2.1 converts the directory to an
EDSTAR file as it's brought in. This
allows SCROLLING MENU to use the
information as a file requestor.

    Normally you would use "$:*" to
get all the disk's filenames. You can
replace "$:*" with any search pattern
you want, up to 16 characters long.
For example, using "$:b.*,t.*" on a
LOADSTAR disk would bring in the
names of all the boot and text files.
(This works on VICE only if True Drive
is enabled.)

    E$ will return the error message.
T$ will contain the disk's name
within quotes, and B$ will contain
the "blocks free" message. Use
VAL(B$) to extract the number of
blocks free on the disk. N% returns
the number of filenames loaded.

    If there was an error during the
directory getting, T$ and B$ will
return strings full of spaces, and E$
will tell about the error. The one
thing your program should do before
disk access is check if the drive is
actually online, like this:

   1000 close2:open2,dv,2:close2
   1010 if st=-128 then...
   1020 ...continue

    Line 1010 would go and deal with
a "device not present" situation. If
all is well, line 1020 executes and
disk access occurs.

    GET DIRECTORY has been greatly
improved with the addition of one
more parameter: how many filenames
you have room to hold. This number
should be calculated as:

   # files = INT((bufferspace-1)/32)

    For example, if your buffer was
from 49152 to 53248, you could fit
INT((4096-1)/32) = 127 names there.
This formula takes into account the
zero cap and the three bytes per line
that the racking process needs.

    If the buffer space is filled up
before all the filenames are loaded,
B$ will return "more files on disk".
If you don't care about buffer space,
use 0 for the number of filenames.


 SCROLLING MENU:
 .ML,<area>,bx,ic,u,h,lc,t$,b$
 -----------------------------

    The <area> represents the x1,x2,
y1,y2 parameters so common to
DotBASIC. (In your code, replace
<area> with the x1,x2,y1,y2
parameters.)

    The x1,x2,y1,y2 parameters set the
area the menu will occupy on the
screen, which must be at least 7
characters tall and 11 wide. BX -
Color for the box around the Scrolling
Menu. IC - Color for the "icons" --
UP, DOWN, HOME, QUIT. U is the color
of the unhighlighted items of the
menu. H is the highlight bar color. If
you don't want the text to reverse or
un-reverse as the bar moves, add 128
to H.

    Left-click on UP or DOWN icons to
scroll the text. Right-click on them
and the list jumps a page at a time.
The user can use the CRSR keys to
scroll or page through the text as
well.

    Clicking on HOME icon will bring
the list to the top. Pressing the
HOME key will bring the highlight bar
to the top of the page, and the next
press brings the list to the top.

    Click on an item or press RETURN
to select it. The entire item is
returned in W$. F$ will return a null
unless this is a file requestor --
when it will contain the filename. SL%
returns the selection number.

    Clicking on QUIT icon, pressing
Q, or pressing the Global Escape key
will return zero in SL% and nulls in
W$ and F$.

    LC is the location of the EDSTAR
file, which can be anywhere in
memory. The file will be "racked up"
before use, which can take up to a
second (gasp!) on 1 MHz machines.
When LC=0, the text file will not be
racked up again -- like when you have
sorted the data. This is better served
for the multi-select menu, if you
wanted to re-enter the menu without
zeroing the "selected" flags. (Read
on!)

    T$ is printed at the menu's top,
in reverse, between HOME and UP. B$
is printed at the bottom, between
QUIT and DOWN. You needn't use the
actual variables T$ and B$, but if
this is going to be a file requestor,
it's perfect. The user gets to see
the disk name and blocks free without
any extra effort from you.!

    Set X2 to 255 and the proper
width for a file requestor will be
assigned, but that's it. DotBASIC
knows what filename info looks like
and will set F$ properly when it finds
a filename - regardless of width.

    NOTE: Using the SCROLLING MENU
with LC not equal to zero changes what
the INDEX routine is cued up to read.
That is, if LC>0 then the data is
Racked.

     An alternate use of LC=0 is, for
example, in a puzzle game. You could
BLOAD WITH ZERO the instructions,
RACK it up right away, and then just
use 0 for LC in the scrolling menu.
The HELP text would pop up quickly,
every time the user needed it.


BUILD YOUR OWN SCROLLING MENUS
-------------------------------

     X1+128 is a powerful new
feature. If you do not like the
generic look of the scrolling menu,
you can now do something about it!

     Several things DON'T happen when
x1+128 is used. The bx,ic,t$, and b$
parameters are IGNORED. The scrolling
menu box is NOT drawn. The previouse
CAGE remains the same. The x1,x2,y1,
y2 parameters now represent the area
for the ACTUAL scrolling text alone.

     "Manual Icons" is just that.
MR.MOUSE is trusting YOU to create,
label, and enable (as regions) the
icons for your scrolling menu. They
can be any size and at any location.

     Since you may not always label
the EXIT icon as "Quit", MV+16 exists
so you can assign an appropriate key
to the exit function. The CRSR keys
still scroll and page, and HOME still
goes home. ESCAPE cancels, just like
EXIT (in the regular scrolling menu).

    For SCROLLING MENU to work, you
must have a RACKED EDSTAR file in
memory, and it must end with a zero
byte. If STAR LINKER is used to place
prepared lists into memory, you will
need to append a zero to each text
file with an ML monitor. (Or use
Mr.Edstar -- which includes the 0 at
the end of the file.)


  MORE ABOUT INDEXING
  -------------------

    When a file is RACKed up by
yourself or a scrolling menu,
MV+24/25 reveal the location of the
text's newly generated pointers. The
number of items in the current
INDEXable file is at MV+26/27. These
two variables, which used to be kept
internally, are now at the disposal
of the advanced programmer.

    By preserving and later restoring
MV+24-27, it is possible to have two
or more INDEXable files in memory at
once, without having to RACK them
(taking almost a second) just so you
can switch between them.

    RACKing also would wipe out all
the "selected" flags stored as bit 7
of each item's LENGTH value. You may
want to preseve MV+24-27 before
calling another scrolling menu so you
do not lose these flags. POKE the
saved values back into MV+24-27 when
it's time to INDEX SELECTED ITEMs.

[NOTE:] Remember, with DotBASIC, you
can Get and Put two-byte values in
memory with single commands. If you
want to preserve the above locations
in I1 and I2, then

   .G2,MV+24,I1:.G2,MV+26,I2

To replace the values

   .P2,MV+24,I1:.P2,MV+26,I2

Simple, eh? DMM


    Yes sir. We have multi-selectable
scrolling menus now! But first, let's
examine the regular SCROLLING MENU:


  MULTI-SELECT SCROLL MENU
  .MV,area,b,i,u,h,s,w,l,t$,b$
  ----------------------------

  area - use x1,x2,y1,y2 in your code
  b    - box color
  i    - icon collor
  u    - unhighlighted color
  h    - highlighted color
  s    - selected color
  w    - selected With bar
  l    - location of file
  t$   - top string
  b$   - bottom string

    It's always easy to spot the
selected items, even when they are
under the highlight bar. Which of the
u,h,s,w items are REVERSED is set
from bits 3-0 to MV+15. By default,
the highlight bar and all selected
items are reversed. Each reverse bit
can be temporarily disobeyed by
adding 128 to the u,h,s,w parameters.

    Selecting items is as easy as
hitting RETURN or clicking on them.
The item is toggled and the mouse and
highlight bar are moved down to the
next item, scrolling when necessary -
even when selecting with the mouse!

    The additional keys A, N, and T
function within multi-select menus to
select ALL, NONE, and to TOGGLE ALL
items (respectively). The mouse user
cannot access these special features
unless YOU enable manual icons!

    Exiting a multi-select menu is the
confusing part. If you press the EXIT
key (MV+16), SL% will return the
number of items selected. If ESCAPE is
pressed, the menu is cancelled and
zero is returned in SL%. The selected
items still exist, and still can be
indexed, but you are just told that
there weren't any selected items.

    Once you have a selected item or
items, use:

  INDEX SELECTED ITEM: .SI,number
  -------------------------------

    This puts the ITEM(Number) into
W$ and (if a Directory) F$. A quick
look at Selected Items could be
accomplished with

            FOR X=1 TO SL%
            SYS .SI,X
            PRINT W$
            NEXT


  PRINT SELECTED ITEM
  .SP,x,y,number
  -------------------

    Does a PRINT AT of the item text,
without affecting W$.


  PRINT SELECTED NAME: .SN,x,y,number
  -----------------------------------

   Does that same as

              P@,x,y,F$

(without affecting F$!

    If you are using manual icons, the
mouse usually can move anywhere on the
screen. Nothing happens if the user
clicks outside the menu. Even clicking
on an active region has no effect IF
the region number isn't one that I've
assigned a function to.

     Here are the REGION NUMBERS and
the functions they would have for a
regular scrolling menu:

     1. home
     2. scroll up
     3. scroll down
     4. exit
     5. page up
     6. page down

     Regions 5 and 6 aren't
necessary, so don't feel obligated to
use them. Nothing bad will happen if
you don't have 6 active regions.
Right-clicking on regions 2 and 3
also PAGE, too.

     MULTI-SELECT SCROLL MENUs will
obey up to four extra regions, if you
take the time to define them.

     7. select all
     8. select none
     9. toggle all
    10. cancel

    Pressing EXIT or clicking on
region 4 will return the number of
selected items in SL%. Region 10
behaves just like ESCAPE, returning a
grand total of zero selected items.

    Remember: When regions overlap,
the higher number has priority. So, if
you don't want regions 5 and 6 in your
multi-select menu, just be sure to
define regions 7 and 8 so they
perfectly overlap the previous two on
the screen!

    However, joystick users with a
repeating fire button may appreciate
regions 5 and 6. No matter what you
decide, be sure to include regions
1-4: the same ones that are present
using the generic "standard" icons.


  SCROLL NUMBER ENABLE
  .S#,current,total,selected
  --------------------------

    You can add that finishing touch
to a scrolling menu with SCROLL
NUMBER. Like the LOADSTAR Presenter's
Text Reader, you can make a message
like "Line 172 of 308" that is updated
each time the infomation changes.
Multi-select menus also show the total
number of SELECTED items.

    The parameters are locations in
memory where the numbers will be POKEd
by this routine. So, to put the
Current line number at the top of the
default screen, the Total just below
it, and ignore Selected, use:

  SYS ML+228,1024,1064,0

    One reason this is a separate
command is because it is RISKY. The
numbers are POKEd to the location you
specify, whether it be the screen or
somewhere it can wreak havoc! So, be
careful when entering these values.

    It takes some time to figure out
the screen location to place each
4-digit number at, but it is worth the
effort. Assign 0 to the numbers that
you choose not to enable.

[NOTE:] Use the PP% variable in a
short program line to let the mouse
find the location!

         .DO:.MA:.UN L2%:?PP%


  VARIOUS OTHER STUFF
  -------------------

    Four variables help to give the
joystick and CRSR keys several degrees
of motion. The minimum and maximum
speeds are measured in "pixels per
interrupt". The acceleration and
deceleration values are more relative.
But don't bother yourself with these
settings: the defaults work quite well
for most applications.

    Sprite Update, the variable at
MV+5, could be set to zero to prevent
the interrupt routine from moving any
sprites at all. It still would keep
track of the "phantom" pointer. I
doubt that this command is of any use.

NOTE: Actually, it DOES have a use.
When you really, really need all 8
sprites during a program and can live
without the mouse -- or can code to
use a character as a mouse, you will
be glad Lee included this varialbe!


    On boot, DotBASIC uses the EASY
SPRITE function to produce a simple
arrow pointer. The upper-leftmost
pixel of that sprite is what is called
the "pointing pixel". As far as
DotBASIC is concerned, that IS the
pointer! All feedback data returned by
the ASK routine is true for that one
pixel only.

    What if you want to design a
mouse-driven shooting game whose
pointer looks like a targeting box?

   Related variables:     (& defaults)

  MV+3  Pointing Pixel-X       (0)
  MV+4  Pointing Pixel-Y       (0)

    Use these variables to define the
pointing pixel within your sprite,
where x=0-23 and y=0-20. Expanded
sprites mean you should double the
proper value(s) here, too.

 LN

 NOTE: These docs have been edited
with the assumption that you will be
doing purely DotBASIC programming.
Mr.Mouse is fully available in
DotBASIC, with a beginning address of
9216. ML coders can also use many of
these commands to great advantage. For
Mr.Mouse address offsets, see issue
177.

 Even as I edit this massive
documentation, I realize that DotBASIC
-- at least the Mr. Mouse portion --
is incredibly powerful. I am still
learning. And you can to!

 DMM