PRTSTR%
                                    =======

       PRTSTR% is a function to print at string to screen - with timeout.

On Qdos systems, or SMSQ/E systems with background screen updating
switched off (PE_BGOFF), if a window is burried - even partially, any
action that attempts to access that window is put on hold until the window
is again free.

So if you have a program that is processing some data in the background,
but also tries to keep the user updated by printing its progress on screen,
that processing is halted should the window become burried. This is not
always desirable!

With background updating switched on (impossible in Qdos without a special
screen driver) background processing can continue and the progress display
is maintained correctly throughout.

PRTSTR% is a poor man's substitution, as it would not maintain such progress
truthfully; if it finds a window unavailable it simply skips the update and
continues processing.

But it is not only printing that is affected by a locked window, setting
the ink or paper colour, as well as positioning commands like AT or CURSOR
will also halt your program. So PRTSTR% packages many of the most likely
functions.


Usage:
======

[ ] => optional
{ } => repeated group, also * => repeat etc
 |  => or

Note the use of separators! They are all significant!

Syntax:

 er% = PRTSTR%(
       [#ch%]                        Channel number (default #1)
       [, timeout%]                  Timeout: -1 = forever, 0 = none (def)
       {                             Repeat this bit:
        [! atx%, aty%] |              AT char position x/y - always two!
        [! atx%! aty%]                AT pix position x/y - always two!
        [TO tabx%]                    TO TAB x-position
        [\ ink [, strip]]             INK and STRIP colour (mode 0..33)
        [; string[$] | char% [, ]* ]  list of strings or (int%) char bytes
       }                             End repeated parameters
      )                              End function

er% contains any IO error code, usually 0 or -1, ie Not Complete.

Paper colour should be set in advance, as PRTSTR% only supports the strip
colour. Also the colour mode, COLOUR_QL, COLOUR_NATIVE, or COLOUR_24
should be set in advance; PRTSTR% supports them all.

To give you a basic idea of how it works, try the PRTSTR_bas program (LRUN it
in an SBASIC). As it runs, cover the window with another program window.
High beep implies no error, low beep usually means not complete. So unless
timeout is set to -1 (wait until complete) the program will keep functioning
even when its window is locked.


Program Status
==============

V0.03, pjw, 2004 Feb 01
V0.03, pjw, 2021 Dec 28, added key and link files for stand-alone version

Conditions and DISCLAIMER as per Knowaree.no