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

(c) Thomas Leonard, 1999-2004, Stephen Fryatt, 2004-2020       29 August 2020
=============================================================================

  A copy of this file is also contained within the IcnClpBrd application.
  It can be accessed from the 'Help' entry in the Filer menu.


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.5 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
  IcnClipBrd 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

  Users of RISC OS 5.27 from 2020 and later, or of RISC OS 4.2x and RISC OS
  Six, will find that IcnClipBrd will be duplicating the native support for
  the clipboard provided by the Window Manager.  Please read the section on
  Use on RISC OS 5 and RISC OS Select for more details.



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

  To use IcnClipBrd the caret must be in a writable icon.  The following keys
  will now work by default, although they can all have their shortcut changed
  or be disabled completely:

  * 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:

  * Swap the case of the character in front of the caret.
  * 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.  If an
  error is encountered when using the contents of the variable, its contents
  is pasted into the icon instead of a date.


  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.

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

    Alternatively, the command can take one or more parameters to change the
    shortcut keys in use as well as enable or disable actions completely.
    The parameters are

    * "-Cut" sets the key for cutting an icon's contents to the clipboard
      (which is Ctrl-X by default).

    * "-Copy" sets the key for copying an icon's contents to the clipboard
      (which is Ctrl-C by default).

    * "-Paste" sets the key for pasting the clipboard into an icon at the
      caret (which is Ctrl-V by default).

    * "-Overwrite" sets the key for overwriting an icon's contents with the
      contents of the clipboard (which is Ctrl-Z by default).

    * "-Extension" sets the key for removing a DOS extension from a filename
      (which is Ctrl-D by default).

    * "-Filename" sets the key for removing the filename to leave a DOS
      extension (which is Ctrl-E by default).

    * "-DelLeft" sets the key for deleting from the caret to the left of the
      text (which is Ctrl-K by default).

    * "-SwapCase" sets the key for swapping the case of the character in
      front of the caret (which is disabled by default).

    * "-DateTime" sets the key for inserting the date and/or time (which is
      disabled by default).

    * "-Quote" sets the key for passing the next keypress on to the taks
      (which is Ctrl-Q by default).

    For example, "*IcnClipBrdKeys --Cut Ctrl-P" would make Ctrl-P cut the
    text from an icon and place it on the clipboard, while "*IcnClipBrdKeys
    --Overwrite Off" would disable the operation to replace an icon's
    contents with the clipboard.

    It is possible to set more than one key shortcut in one command if
    required.

  To adjust the format of the dates inserted by the module, 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".  If an error is encountered when
  IcnClipBrd tries to parse the string, the string itself will be pasted into
  the icon at the caret.

  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.



Use on RISCOS5 and RISCOS Select
-----------------------------------

  Since 2020, RISC OS 5.27 has natively supported the global clipboard in
  writable icons, in a similar manner to RISC OS Select (RISC OS 4 and Six).

  On these systems, it is advisable to allow the Window Manager to handle
  cut, copy and paste operations and leave IcnClpBrd to implement any other
  keypresses that are considered useful.  The main uses of IcnClipBrd on
  these systems are likely to be the case swapping, filename modification and
  date or time insertion operations.

  To achieve this, the "IcnClipBrdKeys -Cut Off -Copy Off -Paste Off
  -Overwrite Off" command can be added to the !IcnClpBrd.Configure file, to
  disable the keys used for clipboard operations.

  It might be desirable to retain the overwrite functaionality of IcnClipBrd,
  but move it to a different keypress so that it does not conflict with the
  standard use of Ctrl-Z for clearing a selection.  One option is to use
  Ctrl-Y, with "IcnClipBrdKeys -Overwrite Ctrl-Y".



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 older versions of 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.  This has been resolved in recent
    versions 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)
  ----------------------

  Limited issue for test purposes.

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


  0.14 (04 July 2009)
  -------------------

  * Fixed serious bug when pasting more than 128 characters by RAM Transfer,
    identified by Fred Graute.


  0.15 (05 July 2009)
  -------------------

  * Date insertion now works correctly with custom format strings.


  0.16 (20 January 2012)
  ----------------------

  * Fixed unaligned memory access in Ctrl-S and Ctrl-D routines.


  0.17 (01 September 2014)
  ------------------------

  * Fix error handling for "*Desktop_IcnClipBrd".


  0.20 (29 August 2020)
  ---------------------

  * Change the use of "*IcnClipBrdKeys" to allow shortcut keys to be changed.



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
