=============================================================================
IcnClipBrd - Global Clipboard in writable icons                  Version 0.13

(C) Thomas Leonard, 1999, Stephen Fryatt 2007                 27 October 2007
=============================================================================


License
-------

  IcnClipBrd is in the public domain and may be freely copied.



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).

  IcnClipBrd, is a small module for users with RISC OS 3.1 or later, which
  allows you to cut and paste in writeable icons using the global clipboard.

  The module was originally written by Thomas Leonard, and has been converted
  to 32-bit for use on RISC OS 5 by myself (Stephen Fryatt).  I would like to
  thank Thomas for allowing the module to be placed in the Public Domain; any
  problems encountered using the updated module are likely to be my fault and
  should be reported first to the address below.



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

  IcnClipBrd requires RISC OS 3.5 or later.

  Installing IcnClipBrd is a matter of running the !IcnClpBrd application
  supplied in the archive.  As standard, this will load the IcnClipBrd module
  and enable all the keypresses described in this manual.  If you wish to run
  IconClipBrd on startup, you should add it to the 'Run list' in Configure.
  To do this, double-click on !Boot, open the 'Boot' option and then open the
  'Run' window.  Drag !IcnClpBrd into the scrolling list and click on the two
  'Set' buttons.

  Earlier versions of IcnClipBrd were supplied as a module on its own.  This
  release can still be used in this way, if the ability to configure the
  available keypresses is not required or if alternative arrangements are
  made.  The IcnClipBrd module can be found inside the !IcnClpBrd
  application.

  If you have a copy of the DeepKeys module installed on your system (it is
  used by a number of applications to provide keyboard handling facilities),
  note that earlier versions can cause a clash with IcnClipBrd and prevent
  text being pasted correctly.  If you experience problems, check that you
  have at least version 2.06 of DeepKeys; recent versions can be found at
  http://sudden.recoil.org/deepkeys.zip



Using the module
----------------

  To use IcnClipBrd the caret must be in a writable icon.  The following keys
  will now work:

  * Ctrl-V pastes the global clipboard into the icon.
  * Ctrl-Z clears the icon, then pastes the clipboard in.
  * Ctrl-C copies the contents of the icon to the clipboard.
  * Ctrl-X cuts the contents to the clipboard (copy then clear).
  * Ctrl-D de-DOSifies the filename in the icon (eg. "NOTES/TXT" would become
    "Notes").
  * Ctrl-E extracts the extension only (eg. "NOTES/TXT" would become "TXT").
  * Ctrl-K deletes everything left of the cursor (not saved to the
    clipboard).
  * Ctrl-Q passes the next keypress on to the task as though IcnClipBrd
    wasn't loaded.

  You can clear the icon without putting the contents on the clipboard by
  using Ctrl-U, as usual.  Ctrl-End will delete the text from the caret to
  the end of the icon.

  In addition to the above, two further keypresses are disabled by default
  but can be configured into use:

  * Ctrl-S swaps the case of the character in front of the caret.
  * <Key>Ctrl-T</key> inserts the date and/or time into the icon.

  By default, dates are in the format DD Mmm YYYY, but other formats
  (including current time) can be defined using the Alarm format field names
  by setting them into the <IcnClipBrd$DateFormat> system variable.


  Configuring the module
  ----------------------

  By default, IcnClipBrd will intercept all of the keypresses listed above
  except for Ctrl-S and Ctrl-T.  This can be configured by the
  "*IcnClipBrdKeys" command.

  *IcnClipBrdKeys [<new keys>]

    The command "*IcnClipBrdKeys" is used to change the keys that the module
    intercepts, or to display the current configuration.

    The <new keys> parameter is a 10-bit binary number, constructed as
    2_TSZXVQKEDC for the ten Ctrl keys.  Thus, enabling only the keys Ctrl-C,
    Ctrl-Q, Ctrl-V, Ctrl-X and Ctrl-Z would require the parameter
    "2_0011110001" (or "&F1", or "241").

    Without a parameter, the command prints a list of the keys currently
    being intercepted.

  To adjust the format of the dates inserted by Ctrl-T, the system variable
  <IcnClipBrd$DateFormat> can be set.  The variable takes the 'Alarm-style'
  date format field names; the default format is DD Mmm YYYY, which would be
  set as "%DY %M3 %CE%YR".

  The !IcnClpBrd application contains an obey file called Configure, which
  calls the "*IcnClipBrdKeys" command and sets the system variable; this
  allows the keys to be set and the date format configured when the module is
  loaded.  Load the file into a text editor to modify it.



Bugs and known issues
---------------------

  Although there are currently no reported bugs in IcnClipBrd, the following
  issues are known to exist:

  * Following corrections made to IcnClipBrd's handling of the data transfer
    protocol in version 0.11, a conflict with StrongED has appeared.  When
    pasting text from StrongED into an icon in a menu or transient dialogue
    box, the target window will close and the text will be pasted into the
    wrong location.  Hopefully this issue should be resolved in a future
    version of StrongED.

  * There are problems pasting text into icons in older versions of NetSurf.
    The problem has been resolved in the NetSurf release versions 1.0 and
    1.1, along with all recent (April 2007 onwards) test builds.



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

  IcnClipBrd was written by Thomas Leonard as part of his Clipboard
  application.  The 32-bit conversion and all updates from version 0.07
  onwards have been done by Stephen Fryatt.



Version History
---------------

  The recent versions of IcnClipBrd are as follows:


  0.06 (04 August 1999)
  ---------------------

  * Final 26-bit release by Thomas Leonard.


  0.07 (13 June 2004)
  -------------------

  Development taken over by Stephen Fryatt

  * First 32-bit version.


  0.08 (28 October 2004)
  ----------------------

  * Fixed a couple of outstanding 32-bit issues identified by Adrian Lees.


  0.09 (11 January 2005)
  ----------------------

  * Removed Ctrl-D and Ctrl-E keypresses.


  0.10 (14 June 2007)
  -------------------

  Alpha release for testing

  * ARMalyser output code tidied, commented and made more maintainable.
  * Fixed some possible 32-bit flag-preservation issues.
  * Fixed YourRef on Message_DataLoadAck.
  * Fixed task handle on Message_RAMFetch in RAMTransmit handler.
  * WimpSlot detected using OS_ReadDynamicArea (making the code require a
    minimum of RISC OS 3.5).
  * RAM Transfer code reinstated.
  * Restored Ctrl-D and Ctrl-E keypresses.


  0.11 (18 June 2007)
  -------------------

  * Command *IcnClipBrdKeys added to allow individual keypresses to be
    disabled.
  * Further tweaks made to data transfer code.


  0.12 (8 August 2007)
  --------------------

  * Fixed pasting of top-bit characters received via RAM Transfer.


  0.13 (27 October 2007)
  ----------------------

  * Uses Territory module for character conversions.
  * Added Ctrl-S to swap case in icons.
  * Added Ctrl-T to insert date and/or time into icons.
  * Further tweaks to top-bit detection in character insert routines.



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

  If you have any comments about the 32-bit version of IcnClipBrd, 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/software/clipboard/

  Stephen Fryatt
  email: steve@stevefryatt.org.uk
