RPT%
                                     ===+

It is possible to write programs that only use the Pointer Interface (PI)
and not the Window Manager (WM) and all that baggage. However, even in
SMSQ/E there is no built-in command to read the pointer. RPT% does the
trick without having to load other toolkits such as ptrmen or Qptr.

Another good reason to use this command over, or on top of, ptrmen's RDPT:
RPT% can also return on job events.

To get a full understanding (in the unlikely event that you dont already
have it!) of the meaning of the parameters, you need to read (part of) the
Qptr manual. It explains the nitty-gritty of termination vectors, special
key codes, events, etc.


RPT% reads the pointer and returns on various conditions:

      subwin% = RPT%([#ch,] tv%, je%, x%, y%, t%) absolute
or
      subwin% = RPT%([#ch,] tv% ! je%, x%, y%, t%) window relative

subwin% is the subwindow number or -1 (Note the separator!)
#ch     is the optional channel no. (default channel #0)
tv%     is termination vector - termination keycode returned in upper byte
je%     is Job Event mask. Returns any events caught in MSbyte
x%/y%   are the current ptr coordinates. (Prime with zero on first call)
t%      is the  timeout 0..32k; -1 => infinite
           On timed out, the termination keycode is -1 ($FFxx)

No need to remove the value returned in the tv% and je% high byte; they are
ignored on the next call.


Termination vector (briefly):
-----------------------------
        1 key stroke
        2 key down
        4 key u p
        8 pointer moved
       16 pointer out of window
       32 pointer in window

      128 special - empty sprite  }
      129 special - move sprite    }  - see Qptr manual before using!
      130 special - resize sprite }

Add values for multiple conditions, eg 1 + 8 => return if pointer moved or
a key was pressed. 32 + 16 => return immediately! "Specials" cannot be
used in this way!

Heres a simple experimentor. RUN in a separate 3-window SBASIC daughter
job. From another SBASIC send it some events, eg SEND_EVENT 'Testing', 33
- sends the event 33 to the job Testing.

10 JOB_NAME 'Testing'
100 tv% = 1: x% = 0: y% = 0: je% = 255: t% = 100
110 CLS
120 ev% = WAIT_EVENT(255, 0): REMark Clear out any pending events
130 REPeat lp
140  sw% = RPT%(tv%, je%, x%, y%, t%)
150  k% = tv% DIV 256: IF k% < -1: k% = k% + 256
160  CLS
170  PRINT 'sw    =', sw%
180  PRINT 'key%  =', k%
190  PRINT 'x%/y% =', x%; '/'; y%
200  PRINT 'ev    =', je% DIV 256
210  PRINT 't     =', t%
220  IF k% = 27: EXIT lp
230 END REPeat lp
:
:

The source code is included so you can see whats going on, and also add it
to your own bespoke toolkit. Its polite to acknowledge where you got it
from, though!

Feedback is welcome, including suggestions, improvements, and bug reports!


Software status:
----------------
V0.00 ©PWitte, July 2oi8
V0.01, pjw, March 25th 2019, modularised
V0.02, pjw, June 4th 2019, safer bp.let (new library)

Conditions of use and discalimer as per Knoware.no