XPASTE - High Resolution "Frame" Restore Documentation - Version 1.0
(c) Paul Bradshaw 72177,2032  (July 15th, '87)


  XPASTE allows you to display a frame that has been saved with XCUT on the
graphics screen.  The High Memory Module must have been installed by XINIT, and
a frame must have been XCUT, before you can use XPASTE.  Here is the syntax of
XPASTE (items in brackets are optional):

XPASTE frmname [[TO] x,y] [(parms)]

  "frmname" is the name of the frame that you wish to see.  This name was
assigned by XCUT.

  "TO x,y" allows you to specify where to display the frame.  If you ommit the
"TO x,y", the frame is displayed exactly where is was XCUT from.  The "TO" is
optional.  Note that when moving the frame, the current version of XPASTE only
allows you to Paste a frame plus or minus 8 pixels from where it was cut from
(XPASTE rounds the values you specify in the "TO x,y" parameter to the nearest
legal location).  In other words, If you "XCUT TEST1 10,7-200,200", then the
commands "XPASTE TEST1 TO 16,7" and "XPASTE TEST1 TO 23,7" place the frame in
exactly the same position (in this case "TO 18,7".  The "18" comes from adding
8 to the x coordinate of the original x coordinate, until you get the closest
number NOT GREATER than the original number).  If this seems complex, don't
worry about it.  The user rarely has to worry about the exact details, and can
use XPASTE as if this didn't happen.  Note that this restriction will be
removed in future versions of XPASTE.

The "parms" are:

IMAGE -  Specify Paste to the IMAGE bank.  Not currently supported.

TEXT  -  Display the text screen during the XPASTE.  The "default" screen will
      be displayed when the Paste is completed.  If TEXT is not specified, the
      screen remains unchanged.

GRON  -  Display the graphics screen during the XPASTE.  The "default screen"
      will be displayed when the Paste is completed.  If GRON is not specified,
      the screen remains unchanged.

SLOW  -  Turn on video waits during the XPASTE.  The "default" video wait
      status will be restored with the Paste is completed.  This parameter
      affects the Micro-Labs board differently -- see XINIT.DOC.  If SLOW is
      not specified, then the wait status remains unchanged.  Use SLOW=N to
      disable video waits.

SWAP  -  Tells XPASTE to "SWAP" the current screen contents with the Frame
      stored in the Buffer Bank.  If you do this command twice in a row, you
      get the effect of "lifting" the frame back up off the screen.  See
      special notes on using the SWAP parameter below.

NOT   -  Tells XPASTE to "invert" (perform a logical "NOT" operation) the frame
      before displaying it.  This does not affect the frame stored in memory.

AND   -  Tells XPASTE to logical "AND" the frame with what is on the screen.
      If a point is lit in the frame AND on the screen, then that point will
      remain lit, otherwise the point will be made dark.

OR    -  Tells XPASTE to logical "OR" the frame with what is on the screen.
      If a point is lit in the frame OR on the screen, then that point will
      remain lit, otherwise the point will be made dark.  This "blends" the
      frame with what is on the screen.

XOR   -  Tells XPASTE to logical "XOR" the frame with what is on the screen.
      If a point is lit in the frame OR on the screen, but NOT BOTH, then that
      point will remain lit, otherwise the point will be made dark.  If you do
      this twice, the second time "restores" the screen to what it was before
      the first time.

NO    -  Suppresses all Output to the Display.  Note that this also suppresses
      all error messages except "Parameter Error", so be careful!

  XPASTE is very powerful.  You can take a frame that has been saved with XCUT,
and move it about the graphics screen, blend it it with the graphics screen, or
paste several copies of the frame all over the screen.  By far the most
powerful feature of XPASTE is the SWAP parameter, which allows you to display a
frame, and then remove it -- regardless of what was underneath, the screen will
be restored.  This allows such things as "pull down menus" and "pop up windows"
to be programmed.

  When using the SWAP parameter, care must be used.  What SWAP does is
"exchange" the frame stored in the Buffer with the area of the screen that the
frame is being pasted to.  After the first "XPASTE frame (SWAP)", the frame
stored in the Buffer bank is actually what was on the graphics screen before
the XPASTE. Before you can use that frame again, you must "XPASTE frame (SWAP)"
again to move the frame back into the Frame Buffer (and at the same time,
restore the screen as it was before).  If you use the "TO x,y" parameter, you
must make sure that the "x,y" is the SAME each time!  And you should not modify
any area of the screen within the frame area between the two XPASTEs (although
that is an easy way of MODIFYING a frame, without having to XCUT a new frame
and use more memory).  In short, each "XPASTE frame (SWAP)" must be paired with
a matching "XPASTE frame SWAP" to function correctly.


Error Messages
==============

This is a listing of the possible error messages reported by XPASTE, along with
their meanings, and possible solutions for "fixing" the error.  The error
number listed is the code returned in the "_ERRRNT" field of the XHRG high
memory module -- a zero is returned for a successful XPASTE operation (see
Technical Notes for further information)

'Parameter Error!' (error #1)
 -- You mis-spelled one of the parameters, forgot to enclose the parameters in
parentheses, or use a parameter other than IMAGE, GRON, TEXT, SLOW, SWAP, AND,
OR, XOR, and NO.

'XINIT must be Installed before using XPASTE' (error #2)
 -- You didn't use XINIT to install the required High Memory Module.  Type
"XINIT" from LS-DOS (or TRSDOS) Ready.

'Illegal or Missing Name' (error #4)
 -- You forgot to specify a frame name, your frame name didn't start with a
letter (A-Z), or your frame name had a character in it other than a letter or
number.  Try another name.

'Illegal Frame Coordinates' (error #8)
 -- Your "TO x,y" coordinates specified a point outside the range of Graphics
Memory.  "x" must be between 0 and 1023 (inclusive), and "y" must be between 0
and 255.

'Frame Not Found!' (error #16)
 -- You have specified a frame that is not stored in the buffer.  Either
check the spelling of the frame name, or make sure that you have used XCUT
to cut a frame by that name.

'Syntax Error in Coordinates' (error #32)
 -- You didn't separate your coordinates with commas, or you typed a space
or other illegal character inside your coordinates.  You may have also
mis-spelled the "TO".

'Frame Name too Long!' (error #64)
 -- The name of your Frame must be 8 characters or less.

'There is no Frame Buffer assigned!' (error #128)
 -- You must use the "BUFFER" parameter of XINIT to assign a bank for use as a
frame buffer.  Use "XINIT (B=n)", where 'n' is the number of the bank you wish
to use.


==========


  This software is Copyright 1987 by Paul Bradshaw, and is distributed as
"ShareWare".  You are free to copy and/or give away this software to anyone, or
post it on any other bulletin boards for private use PROVIDING that the program
and documentation (including this statement) are kept intact, unaltered, and
bundled together, and that no charge shall be made for such distribution of any
kind without the written permission of the author.  A $5 contribution may be
made to:

Paul Bradshaw
1372 West Second Ave
Columbus OH  43212

  For this $5, you will be registered as an owner of this software, and
immediately notified of any fixes, updates, and/or further additions and
enhancements.  This $5 covers this program, the XINIT program, and the XCUT
program only.  If you do not register yourself as a user, please erase this
program and documentation from your disks.  Thank you, and I hope you like this
program.  Please forward any suggestions and/or comments to the above address,
or directly to me via CompuServe EasyPlex [72177,2032].  Enjoy!
