Loadstar 236/236.d81/t.dbdocs4

Text File | 2022-08-26 | 14KB | 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 f