=============================================================================
Clipper - A Global Clipboard utility                             Version 0.32

(c) Thomas Leonard, 1999-2004, Stephen Fryatt, 2004-2022        20 March 2022
=============================================================================


  This file is also contained within the Clipper application and can be
  accessed from the 'Help' entries in the Filer menu and Clipper's
  iconbar menu.



License
-------

  Clipper is licensed under the EUPL, Version 1.2 only (the "Licence"); you
  may not use this work except in compliance with the Licence.

  You may obtain a copy of the Licence at
  http://joinup.ec.europa.eu/software/page/eupl

  Unless required by applicable law or agreed to in writing, software
  distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  See the Licence for the specific language governing permissions and
  limitations under the Licence.

  The source for Clipper can be found on GitHub, at
  https://github.com/steve-fryatt/clipper



Introduction
------------

  The global clipboard provides a way of transferring data between
  applications.  You select the data in one application and cut or copy it
  onto the clipboard (usually using Ctrl-X and Ctrl-C).  You then move to the
  other application and paste the data from the clipboard (usually Ctrl-V).

  Clipper allows you to save the current contents of the global clipboard,
  either to disc or to another application.  You can also drag files from a
  filer window to Clipper to put that file on the clipboard, and type the
  clipboard contents to the caret.

  The IcnClipBrd module, which allows you to cut and paste in writeable icons
  using the global clipboard, is no longer supplied with Clipper, but is
  available from http://www.stevefryatt.org.uk/risc-os/clipboard.

  The Clipper utility was originally called Clipboard and written, along with
  the IcnClipBrd module, by Thomas Leonard.  It was converted to 32-bit for
  use on RISC OS 5 by myself (Stephen Fryatt), and was renamed Clipper in
  2020 to resolve a clash with a legitimately-allocated application name.  I
  would like to thank Thomas for allowing his code to be placed in the Public
  Domain; any problems encountered using the updated application and module
  are likely to be my fault and should be reported first to the address
  below.



Installation
------------

  To use Clipper, simply run it from a Filer window.  If you always want it
  on the iconbar, it can be included in the list of applications to be run at
  startup in the 'Boot' section of Configure.



Using Clipper
-------------

  Once Clipper is loaded, it will install an icon on the iconbar.  Click
  Select on this icon to open the Save clipboard window.  If there is
  anything on the clipboard then you will be able to drag the icon to a
  directory or to another application to save the clipboard.  You can put a
  file onto the clipboard by dragging it to this window.

  If you toggle the window size then you can see an extra box which indicates
  what Clipper is doing.  This may be helpful for programmers trying to work
  out why their program doesn't work with Clipper.  Note that the problem may
  well be Clipper's fault!

  If there is text on the clipboard, an Adjust click on the iconbar icon will
  type it at the caret.  Only those characters which are considered to be
  either not control characters or white space will be included in the text;
  content including newlines and carriage returns might not have the expected
  effects.



Other information
-----------------

  Clipper was written by Thomas Leonard.  The 32-bit conversion was done by
  Stephen Fryatt.



History
-------


  Version 0.01 (20 October 1996)
  ------------------------------

  * Main window shows type and owner of clipboard and allows user to put
    things on the clipboard by dragging to the window.


  Version 0.02 (21 October 1996)
  ------------------------------

  * Added menu and info window.
  * User can save clipboard to filer or to another app (lots of fun with
    "Wimp_SendMessage"!).


  Version 0.03 (22 October 1996)
  ------------------------------

  * Wrote most of IcnClipBrd including transfer of clipboard via "Wimp$Scrap"
    and sending using RAM transfer (but not yet receiving data this way).


  Version 0.04 (23 October 1996)
  ------------------------------

  * Added support for RAM fetch, but had to remove it because it didn't work
    with some programs which close all menus when you use RAM transfer!


  Version 0.05 (08 September 1998)
  --------------------------------

  * Made WimpSlot 36K, as someone said it wouldn't run on their computer with
    32K.  Changed the window layout to make the Owner box bigger.
  * Fixed serious bug -- didn't work if <Wimp$Scrap> already existed!


  Version 0.06 (15 September 1998)
  --------------------------------

  * Made WimpSlot 40K, as someone else still couldn't run it!
  * Removed Shift from all the IcnClipBrd key-combos.
  * Added protocol status report box, and made it work better with Zap
    (though still not perfect).


  Version 0.07 (17 September 1998)
  --------------------------------

  * Doesn't bring the window to the front when an error occurs unless the
    window was already open.
  * Fixed protocol bug -- window handle and icon handle got corrupted when
    dragging a file owned by one application to another application.


  Version 0.08 (17 September 1998)
  --------------------------------

  * Now acks "Message_DataLoad" when copying from one task to another, since
    the clipboard owner could decide that the receiver had died and delete
    the scrap file.
  * Bugfix: IcnClipBrd treated any "Claim_Entity" message as a claim for the
    global clipboard.


  Version 0.09 (24 July 1999)
  ---------------------------

  * Added Ctrl-E and Ctrl-K keys to IcnClipBrd; requested by Bob Pollard and
    Stewy.


  Version 0.10 (04 August 1999)
  -----------------------------

  * Fixed bug in pasting routines -- top-bit-set chars didn't have a leading
    zero byte added.


  Version 0.11 (07 July 2004)
  ---------------------------

  Updated by Stephen Fryatt

  * Included 32-bit version of the IcnClipBrd module.


  Version 0.12 (05 March 2005)
  ----------------------------

  Updated by Stephen Fryatt and Kell Gatherer

  * Added documentation links to iconbar menu and Program info window.


  Version 0.13 (04 August 2007)
  -----------------------------

  Updated by Stephen Fryatt

  * Included IcnClipBrd 0.11.


  Version 0.14 (08 August 2007)
  -----------------------------

  Updated by Stephen Fryatt

  * IcnClipBrd module removed from Clipper, and supplied separately to
    simplify future updates.


  Version 0.15 (03 September 2014)
  --------------------------------

  Updated by Stephen Fryatt

  * Converted source to generic build system usning Tokenize.
  * Fixed broken code in URI dispatch, including adding missing error
    handling routines.
  * Correctly close Templates file after use.


  Version 0.20 (13 June 2020)
  ---------------------------

  Second beta release.

  * Renamed from Clipboard to Clipper to avoid an allocation clash.
  * Licence changed to EUPL, following extensive refactoring of the code, to
    reflect the significant use of WimpLib in the application.
  * Removed TAL icon from program information window to avoid adding an
    un-allocated sprite name to Wimp Sprite Pool.
  * Add support for Interactive Help throughout the application.
  * Extensive code refactoring, including the use of WimpLib for common
    tasks.
  * Fix Data Transfer Protocol implementation, including several missing
    DataLoadAck messages.
  * Watch for the application owning the clipboard quitting (ticket #712).


  Version 0.30 (29 August 2020)
  -----------------------------

  Third beta release.

  * Licence updated to EUPL v1.2.
  * Adjust-clicks on the iconbar icon type the clipboard contents at the
    caret (ticket #725).
  * Provide better support for applications which don't respond well to
    requests for the clipboard contents (tickets #714 and #715).
  * Use ResConf-style system variables to identify resources.
  * Fall back to the unknown file icon when the Wimp pool doesn't contain a
    suitable icon for the clipboard contents (ticket #713).


  Version 0.31 (27 October 2020)
  ------------------------------

  Update to third beta release.

  * Include whitespace characters in typed content (Ticket #726).
  * Add missing ENDCASE in bounced message handling routine (Ticket #727).
  * Remove an attempt to type the clipboard contents in the case of a direct
    save from another owner.


  Version 0.32 (20 March 2020)
  ----------------------------

  Update to third beta release.

  * Examine clipboard on Null events, to avoid clashes with other software
    doing the same thing.



Updates and Contacting Me
-------------------------

  If you have any comments about the 32-bit version of Clipper and, or
  would like to report any bugs that you find, you can email me at the
  address below.

  Any updates to the module will be made available on my website, at
  http://www.stevefryatt.org.uk/risc-os/clipboard

  Stephen Fryatt
  email: info@stevefryatt.org.uk
