Loadstar 236/236.d81/t.dbdocs2

Text File | 2022-08-26 | 11KB | 432 lines

u
        DOTBASIC DOCUMENTATION
                Part 3


    Welcome back! Let's get on with
screen manipulation:


  CUT:   .TC,x1,x2,y1,y2,loc
  PASTE: .TP,x1,x2,y1,y2,loc
  --------------------------

    CUT and PASTE are able to stash
and restore any size portion of the
screen to or from any location, even
under I/O.

    The data is stored sequentially in
memory with each cell's screen code
and color code stored one after
another. This formula reveals how much
memory is consumed by CUT:

   bytes = (x2-x1+1)*(y2-y1+1)*2

    PASTE requires that you specify
the area to be filled. As long as you
use the same SIZE area as the cut
data, you can PASTE it wherever you
want, oodles of times.


NOTE: DotBASIC has a better way! PASTE
requires that the dimensions of the
PASTEd "object" are the same as the
CUT. This can be a hassle!

    So we have added OBJECT commands.

    First off, you must assign a
location in memory for your objects.
As with CUT and PASTE, the location
can be anywhere, even under I/O.


  OBJECT SET: .OS,location
  ------------------------

    This sets a place for NEW ojects
and zeros the number of objects
present.


  OBJECT LINK: .OL,location
  -------------------------

    This links the Object commands to
a location in memory without zeroing
the number of objects present --
perfect when you BLOAD an Object File.


  OBJECT CUT: .OC,x1,x2,y1,y2
  ---------------------------

    The cut object is placed in the
next slot in the object area. The
end+1 of the object area is returned
in FP (for checking memory and
BSAVEing).


  OBJECT PASTE: .OP,index,x,y
  ---------------------------

    This puts the indexed object on
the screen, with x/y being the
position of the upper left corner.


  OBJECT DELETE: .OD
  ------------------

    This removes the last object.


  OBJECT NUMBER: O#
  -----------------

    Returns the number of objects in
the collection in I%.



  CHECK KEYPRESS: .KP,string
  --------------------------

    This routine quickly scans your
string and checks if any of those keys
are being pressed at the moment. If
one is, that key's position within the
string will be returned in I%.

   Example: SYS ML+60,"dragon"

     If an "a" was being pressed, I%
would return a value of 3. If no keys
were being pressed, I% returns zero.
Although the CRSR/RETURN keys already
offer a means of "keyboard support",
do not forget to add the convenience
of hotkeys to your program!

  BIG NOTE: Some mouse buttons are
mistaken for keyboard presses!

  Mouse   Usually  Can also be
  Button  Seen as  Mistaken for
  ------  -------  ------------
  Left     SPACE   <RShift> .MBCZ <F1>
  Right   nothing  \+97531 <Delete>
  Middle  b.arrow  *PIYRW <Return>


  LET GO: .KR
  -----------

    This command will wait until the
user is not holding either of the
mouse buttons (or their equivalents)
down, even if it takes all day.


  COPYMEM:(,start,end+1,destination)
  ----------------------------------
   COPY MEM:          .CP,params
   SWAP MEM:          .SW,params
   COPY I/O INTACT:   .CI,params
   COPY CHR EXPOSED:  .CC,params

    COPY MEM is the classic command.
All ROMS are lifted and a raw memory
transfer is performed. The speed:
approximately 28 cycles per byte.

    SWAP MEM will swap the area of
memory with that at the destination,
at a rate of 41 cycles per byte.

    COPY I/O INTACT will lift the
ROMS, but leave the $d000 area alone.
This would be useful in copying the
color RAM or the VIC-chip's settings.

    COPY CHAR EXPOSED will lift the
ROMS, but expose the Character-ROM in
the $d000 area so you can copy it.

    These routines all work under the
protection of a SEI. When done, all
ROMS are switched back in regardless
of what location 1 held when called.
In fact, this goes for all routines
that switch out the ROMS.

[Note:] Routines that operate under
an SEI and may take over 1/60 of a
second to complete, like STASH and
COPYMEM, take a short break every so
often to let the interrupt "pass by".
While this isn't really important, it
does keep the mouse moving fluidly
even during large memory transfers.


  REGULAR MENU:
  .MU,x1,x2,y1,y2,u,h,"hotkeys"
  -----------------------------

    This command creates a highlight
bar that moves in sync with the mouse
pointer, until a selection is made.
When an item is clicked on, SL% will
return that "selection" number, which
will be anywhere from 1 to 25.

    U is the color of unhighlighted
items in the menu. The highlight bar
is colored H. If you do not want the
text to reverse or un-reverse as the
bar moves, add 128 to H.

    You can also use the CRSR/RETURN
keys instead of a mouse or joystick.
In order to provide a more natural
menu interface, the "Keyboard Enable"
variable at MV+20 is temporarily
zeroed during menus. The CRSR keys are
then read manually to move the
highlight bar, one move per press,
like we're all used to.

    The HOTKEY string allows direct
selection of menu items. For example,
if you have hotkeys of "loadst*r", and
the user presses "d", the fourth item
is selected and the highlight bar is
moved there. If there was no such
item, SL% still returns a 4 but the
highlight bar would not change.

    MENUS can have "regions active"
without the need to POKE to MV+10 or
MV+11. Clicking on an active region
from a menu will return the region
number (plus 128) in SL%. The HOTKEYS
would return "region-like" values.

    The H+64 feature of menus will
only work if "honor hotkey colors" is
enabled. A HOTKEY COLOR is just ANY
color within the text of a menu which
is neither the highlight nor
un-highlight color. That leaves you
with 14 colors to make your menu's
hotkeys stand out, and stay that way.

   Related Variables:     (& defaults)

  MV+10  Menu Type            (192)
  MV+12  Global Escape          (0)

    MV+12 holds the ASCII code for
what you'd like to designate as the
escape key for ALL your menus. SL%
returns a zero when the escape key is
pressed, except in one instance...

    MV+10 dictates how your regular
menus will behave. Each bit stands for
a specific menu feature. Just add up
the values for the features you want
and POKE that number to MV+10.

   +128  Automatic Caging of Mouse
   + 64  Automatic Point-to-First
   + 32  Must Select
   + 16  Escape Equal-to-Last
   +  8  Honor Hotkey Colors
   +  4  Dual Response
   +  2  Un-highlight after Select
   +  1  Stray-to-Exit

  +128 causes the mouse to be confined
    within the menu's borders. After a
    selection is made, the previous
    cage is restored. If auto-caging
    is not enabled, the user may be
    able to click on the area outside
    of the menu, which would return
    zero in SL% (unless it is an
    active region).

  +64 causes the mouse to be put at
    the rightmost cell of the first
    item the instant a regular menu is
    called.

  +32 causes nothing to happen if the
    user clicks on the area outside of
    the menu. The menu remains active
    as it waits for a real selection.

  +16 causes the escape key, when
    pressed, to automatically select
    the last item in your menu - just
    as if you pressed its hotkey. This
    saves some code if "Close this
    Menu" is the last item in your
    menus - especially when using the
    ON GOTO command.

  +8 causes the highlight bar to not
    change the colors of characters
    that have neither the Highlight
    nor Un-highlight color applied to
    them.

    This is an interesting way to
    inform users of your menu's
    hotkeys. To use this feature
    properly, you must make sure the
    entire menu area is colored in the
    Un-hilight color, except for the
    hotkey-characters.

    Merely PRINTing your menu items
    and calling the menu won't work
    right on older versions of the
    KERNAL. The areas on the right
    sides of your items might be
    colored white, or have the cursor
    color or background color applied
    to them. It's best to use BOX to
    draw a rectangle of spaces, THEN
    print your menu items.

  +2 causes the highlight bar to be
    removed after a selection is made.

  +1 causes the menu to be aborted if
    the mouse strays from the menu
    area. SL% is returned as zero