14 - Mouse

 "Q: What were you in civilian life?"
 "A: Happy, sir!"

                YOUR SECOND GFA BASIC 3.XX MANUAL
                             - or -
        HOW I LEARNED TO STOP WORRYING AND LOVE GFA-BASIC
                             PART 15
                    CHAPTER FOURTEEN - MOUSE
                          by Han Kempen

Editor

 Sometimes  the  editor  seems  to freeze  while  the  cursor  is
blinking rapidly.  Just move the mouse and the editor comes alive
again.

Fileselector

 Sometimes  the  same blinking mouse appears  after  calling  the
Fileselector or an Alert-box.  I've read somewhere this could  be
due  to the combination of a VDI-function (for the mouse) and  an
AES-function (for Fileselector or Alert-box).  GFA takes care  of
the  first  and GEM of the second,  and sometimes this  seems  to
result in a conflict.

MOUSE

 If  you  repeatedly  call a Procedure in which you  test  for  a
mouse-click  (with  MOUSE or MOUSEK),  you should  incorporate  a
short  pause  in the Procedure  (e.g.  PAUSE  5).  Otherwise  the
Procedure  might be called again while the user is still  holding
the button down.  You could also wait until the user releases the
button:

     REPEAT
     UNTIL MOUSEK=0      ! wait until button is released

 If you find it difficult to move the mouse accurately, you could
use  <Shift>  <Alternate> <Arrow> to move  the  mouse-cursor  one
pixel  in the desired direction.  If you press <Insert> as  well,
you  can 'drag' something accurately as if the left  mouse-button
was  pressed.  You  can simulate several mouse-actions  with  the
keyboard:

     <Alt><Arrow>                   - move mouse-cursor 16 pixels
     <Shift><Alt><Arrow>            - move 1 pixel
     <Alt><Insert>                  - click left button
     <Alt><ClrHome>                 - click right button
     <Alt><Insert><Arrow>           - hold left button down and
                                          move (16)
     <Shift><Alt><Insert><Arrow>    - hold left button down and
                                          move (1)
     <Alt><ClrHome><Arrow>          - hold right button down and
                                          move (16)
     <Shift><Alt><ClrHome><Arrow>   - hold right button down and
                                          move (1)

 You can find the maximal x- and y-coordinates of the mouse with:

     x=DPEEK(&H9862)
     y=DPEEK(&H9864)

 But  there's  no guaranty you will find the  coordinates  there.
Experiment with XBIOS 0 for a more reliable method.  Don't ask me
how (this method will only work on one specific TOS  version,  as
it uses undocumented system variables, ED.).

 MOUSE  returns negative coordinates if the mouse is to the  left
of  or  above  the current window (or the origin  that  has  been
selected with CLIP OFFSET).

 If  the  mouse is visible (SHOWM) and you put something  on  the
screen (e.g.  with PRINT or PUT),  the mouse is turned  off.  The
advantage  is that you can't destroy the screen under the  mouse-
cursor. The disadvantage is that you could see a rapidly blinking
mouse if you repeatedly put something on the screen. The cure for
this problem is to wait until the user actually moves the  mouse,
but  then  the mouse will still flicker during  movement  of  the
mouse.  The  cure for that problem is to wait until the mouse  is
stationary again. Now there will be no flickering at all:

     SHOWM
     MOUSE x1,y1,k            ! where is the mouse now?
     REPEAT
       MOUSE x,y,k
     UNTIL x1<>x OR y1<>y     ! wait until mouse is moved
     REPEAT
       x1=x
       y1=y
       PAUSE 1
       MOUSE x,y,k
     UNTIL x1=x AND y1=y      ! wait until mouse is stationary
                                 again

SETMOUSE

 A mouseclick can be simulated with:

     SETMOUSE mx,my,mk

 If you try this with an Alert-button you have to move the  mouse
after-wards,  or the button won't be selected.  I don't know why,
so I can't tell if this is a bug.

 If  you use SETMOUSE before ALERT,  you won't be able to  choose
the  default ALERT-button with <Return>.  Sometimes it  helps  to
insert this before ALERT:

     REPEAT
     UNTIL MOUSEK=0

 But this doesn't help always. I do know it's impossible to use a
default-button in those cases, but I have no idea why.

HIDEM

 Although the mouse-cursor is invisible after HIDEM, the mouse is
still monitored by the operating system. If you move the mouse it
will  take  time to process the movement and this will  slow  the
program  down.  You  could prevent that by  switching  the  mouse
temporarily off:

     OUT 4,18       ! disable mouse
     (...)          ! mouse can't disturb us here
     OUT 4,8        ! activate mouse again

 Disabling  the  mouse will not result in  your  program  running
faster, except when a nervous user keeps moving the mouse all the
time.

DEFMOUSE

 In  a  compiled  program it's a good idea to  use  'DEFMOUSE  0'
(arrow)  because GEM leaves the bee behind as  the  mouse-cursor.
GEM  also  switches  the mouse-cursor off,  so you  have  to  use
'SHOWM'  if  you  need a visible mouse-cursor  in  your  compiled
program.

 After  FILESELECT  or ALERT the mouse-cursor is changed  to  the
default-arrow.  Use  DEFMOUSE (again) if you need another  cursor
after FILESELECT or ALERT.

 You  can  use  one of the many Public  Domain  mouse-editors  to
design your own mouse-mutant.  But it's also easy to create a new
mouse-cursor in your GFA-program:

     ' Construct mouse-string (37 words) from data in DATA-lines
     RESTORE pattern.mouse
     m$=STRING$(74,0)                           ! prevent garbage
     READ x,y,mode,msk.color,mouse.color
     MID$(m$,1,2)=MKI$(x)                          ! word 1
     MID$(m$,3,2)=MKI$(y)                          ! word 2
     MID$(m$,5,2)=MKI$(mode)                       ! word 3
     MID$(m$,7,2)=MKI$(msk.color)                  ! word 4
     MID$(m$,9,2)=MKI$(mouse.color)                ! word 5
     FOR n=1 TO 16                                 ! word 6-21
       READ msk$
       MID$(m$,9+n*2,2)=MKI$(VAL("&X"+msk$))
     NEXT n
     FOR n=1 TO 16                                 ! word 22-37
       READ mouse$
       MID$(m$,41+n*2,2)=MKI$(VAL("&X"+mouse$))
     NEXT n
     '
     DEFMOUSE m$                            ! activate new mouse
     '
     pattern.mouse:
     ' x,y,mode(0=normal;1=XOR),mask-colour,mouse-colour
     DATA 0,0,0,0,1
     '
     ' mask-pattern (1 = pixel on , 0 = pixel off)
     DATA 0000111111110000
     DATA 0001111111111000
     DATA 0011111111111100
     DATA 0111111111111110
     DATA 0111111111111110
     DATA 0111111111111110
     DATA 0111111111111110
     DATA 1111111111111111
     DATA 1111111111111111
     DATA 1111111111111111
     DATA 0111111111111110
     DATA 0111111111111110
     DATA 0111111111111110
     DATA 0011111111111100
     DATA 0001111111111000
     DATA 0000111111110000
     '
     ' mouse-pattern (1 = pixel on , 0 = pixel off)
     DATA 0000000000000000
     DATA 0000111111110000
     DATA 0001111111111000
     DATA 0011111111111100
     DATA 0010000000000100
     DATA 0010011001100100
     DATA 0010000100000100
     DATA 0110001000000110
     DATA 0110010000000110
     DATA 0110011110000110
     DATA 0010000000000100
     DATA 0010100000010100
     DATA 0010011111100100
     DATA 0001000000001000
     DATA 0000111111110000
     DATA 0000000000000000

 The  mask  should be an exact copy of the mouse-pattern  if  you
need  a transparant mouse-cursor,  although the cursor will  look
better  if the mask is one pixel larger than the outline  of  the
mouse-pattern.  Leave the mask empty (all '0') and the mouse will
disappear  behind objects on the screen.  Fill the mask with  '1'
and the 16x16 mouse will always remain visible.  Switch mask- and
mouse-colour in the first DATA-line to create a 'reverse'  mouse.
Or  use  any VDI colour-index that is available  in  the  current
resolution.

 A  strange  phenomenon  (also called a bug) occurs  if  you  use
DEFMOUSE  while the mouse-cursor is at the top of the screen  and
you click the left button.  The program freezes,  but if you move
the mouse-cursor down the screen the program continues  normally.
This  happens if the mouse is located in the "menu-part"  of  the
screen (0 ? y ? 18),  even if there is no menu.  I could  pretend
that  I  know  exactly  what is happening  by  stating  that  GFA
probably  uses  Graf_mkstate  (GEMSYS 79)  and  this  causes  the
problem. Actually I have no idea what's going on.

                     Procedures (CHAPTER.14)

Mouse_action                                             MOUS_ACT
 Wait until the user moves the mouse:
     @mouse_action(FALSE,x,y,k)
 Mouse-coordinates and button-state are returned.  If the flag is
TRUE  the  Procedure waits until the mouse  is  stationary  again
before  returning  the  coordinates.  A  button-press  is  always
returned immediately.

Mouse_init_1 and Mouse_create                            MOUSINIT
 Create  a new mouse-cursor (mask and mouse are stored  in  DATA-
lines):
     @mouse_init_1(mouse$)
     DEFMOUSE mouse$
 Other  cursors could be stored in  other  Mouse_init-Procedures.
The  actual  construction  of the  mouse-string  takes  place  in
Procedure Mouse_create.

Mouse                                                       MOUSE
 Disable mouse temporarily:
     @mouse(FALSE)     ! disable mouse
     (...)             ! playing with the mouse doesn't slow
                          program down
     @mouse(TRUE)      ! activate mouse again