<document title="IcnClipBrd">
<define name="version" value="0.16">
<define name="date" value="20 January 2012" length=20 align="right">





<literal mode="Text">
=============================================================================
IcnClipBrd - Global Clipboard in writable icons                  Version $$version$$

(c) Thomas Leonard, 1999-2004, Stephen Fryatt, 2004-2020 $$date$$
=============================================================================
</literal>







<chapter title="License" file="License">

<cite>IcnClipBrd</cite> is in the public domain and may be freely copied.

</chapter>




<chapter title="Introduction" file="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 <key>ctrl-X</key> and <key>ctrl-C</key>). You then move to the other application and paste the data from the clipboard (usually <key>ctrl-V</key>).

<cite>IcnClipBrd</cite>, is a small module for users with RISC&nbsp;OS&nbsp;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&nbsp;OS&nbsp;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.

</chapter>




<chapter title="Installation" file="Installation">

<cite>IcnClipBrd</cite> requires RISC&nbsp;OS&nbsp;3.5 or later.

Installing <cite>IcnClipBrd</cite> is a matter of running the <file>!IcnClpBrd</file> 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 <cite>IcnClipBrd</cite> on startup, you should add it to the &lsquo;Run list&rsquo; in <cite>Configure</cite>. To do this, double-click on <file>!Boot</file>, open the <icon>Boot</icon> option and then open the <icon>Run</icon> window. Drag <file>!IcnClpBrd</file> into the scrolling list and click on the two <icon>Set</icon> buttons.

Earlier versions of <cite>IcnClipBrd</cite> 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 <file>IcnClipBrd</file> module can be found inside the <file>!IcnClpBrd</file> application.

If you have a copy of the <cite>DeepKeys</cite> 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 <cite>IcnClipBrd</cite> and prevent text being pasted correctly. If you experience problems, check that you have at least version 2.06 of <cite>DeepKeys</cite>; recent versions can be found at <link ref="http://sudden.recoil.org/deepkeys.zip">http://sudden.recoil.org/deepkeys.zip</link>

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

</chapter>





<chapter title="Using the module" file="Use">

To use <cite>IcnClipBrd</cite> 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:

<list>
<li><key>Ctrl-V</key> pastes the global clipboard into the icon.

<li><key>Ctrl-Z</key> clears the icon, then pastes the clipboard in.

<li><key>Ctrl-C</key> copies the contents of the icon to the clipboard.

<li><key>Ctrl-X</key> cuts the contents to the clipboard (copy then clear).

<li><key>Ctrl-D</key> de-DOSifies the filename in the icon (eg. <code>NOTES/TXT</code> would become <code>Notes</code>).

<li><key>Ctrl-E</key> extracts the extension only (eg. <code>NOTES/TXT</code> would become <code>TXT</code>).

<li><key>Ctrl-K</key> deletes everything left of the cursor (not saved to the clipboard).

<li><key>Ctrl-Q</key> passes the next keypress on to the task as though IcnClipBrd wasn&rsquo;t loaded.
</list>

You can clear the icon without putting the contents on the clipboard by using <key>Ctrl-U</key>, as usual. <key>Ctrl-End</key> 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:

<list>
<li>Swap the case of the character in front of the caret.

<li>Inserts the date and/or time into the icon.
</list>

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 &lt;IcnClipBrd$DateFormat&gt; 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.


<subhead title="Configuring the module">

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

<comdef target="*IcnClipBrdKeys" params="[&lt;new keys&gt;]">

The command <command>*IcnClipBrdKeys</command> 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

<list spacing=1>
<li><command>-Cut</command> sets the key for cutting an icon&rsquo;s contents to the clipboard (which is <key>Ctrl-X</key> by default).
<li><command>-Copy</command> sets the key for copying an icon&rsquo;s contents to the clipboard (which is <key>Ctrl-C</key> by default).
<li><command>-Paste</command> sets the key for pasting the clipboard into an icon at the caret (which is <key>Ctrl-V</key> by default).
<li><command>-Overwrite</command> sets the key for overwriting an icon&rsquo;s contents with the contents of the clipboard (which is <key>Ctrl-Z</key> by default).
<li><command>-Extension</command> sets the key for removing a DOS extension from a filename (which is <key>Ctrl-D</key> by default).
<li><command>-Filename</command> sets the key for removing the filename to leave a DOS extension (which is <key>Ctrl-E</key> by default).
<li><command>-DelLeft</command> sets the key for deleting from the caret to the left of the text (which is <key>Ctrl-K</key> by default).
<li><command>-SwapCase</command> sets the key for swapping the case of the character in front of the caret (which is disabled by default).
<li><command>-DateTime</command> sets the key for inserting the date and/or time (which is disabled by default).
<li><command>-Quote</command> sets the key for passing the next keypress on to the taks (which is <key>Ctrl-Q</key> by default).
</list>

For example, <command>*IcnClipBrdKeys --Cut Ctrl-P</command> would make <key>Ctrl-P</key> cut the text from an icon and place it on the clipboard, while <command>*IcnClipBrdKeys --Overwrite Off</command> would disable the operation to replace an icon&rsquo;s contents with the clipboard.

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

</comdef>

To adjust the format of the dates inserted by the module, the system variable &lt;IcnClipBrd$DateFormat&gt; can be set. The variable takes the &lsquo;Alarm-style&rsquo; date format field names; the default format is DD Mmm YYYY, which would be set as <code>%DY %M3 %CE%YR</code>. If an error is encountered when <cite>IcnClipBrd</cite> tries to parse the string, the string itself will be pasted into the icon at the caret.

The <file>!IcnClpBrd</file> application contains an obey file called <file>Configure</file>, which calls the <command>*IcnClipBrdKeys</command> 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.

</chapter>



<chapter title="Use on RISC&nbsp;OS&nbsp;5 and RISC&nbsp;OS Select" file="Ro5Select">

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

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

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

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

</chapter>


<chapter title="Bugs and known issues" file="Bugs">

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

<list spacing=1>
<li>Following corrections made to <cite>IcnClipBrd</cite>&rsquo;s handling of the data transfer protocol in version 0.11, a conflict with older versions of <cite>StrongED</cite> has appeared. When pasting text from <cite>StrongED</cite> 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 <cite>StrongED</cite>.

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

</chapter>




<chapter title="Other information" file="Extra">

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

</chapter>




<chapter title="Version History" file="History">

The recent versions of <cite>IcnClipBrd</cite> are as follows:

<subhead title="0.06 (04 August 1999)">

<list>
<li>Final 26-bit release by Thomas Leonard.
</list>

<subhead title="0.07 (13 June 2004)">

Development taken over by Stephen Fryatt

<list>
<li>First 32-bit version.
</list>


<subhead title="0.08 (28 October 2004)">

<list>
<li>Fixed a couple of outstanding 32-bit issues identified by Adrian Lees.
</list>


<subhead title="0.09 (11 January 2005)">

<list>
<li>Removed <key>Ctrl-D</key> and <key>Ctrl-E</key> keypresses.
</list>


<subhead title="0.10 (14 June 2007)">

Alpha release for testing

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


<subhead title="0.11 (18 June 2007)">

<list>
<li>Command <command>*IcnClipBrdKeys</command> added to allow individual keypresses to be disabled.
<li>Further tweaks made to data transfer code.
</list>


<subhead title="0.12 (8 August 2007)">

<list>
<li>Fixed pasting of top-bit characters received via RAM Transfer.
</list>


<subhead title="0.13 (27 October 2007)">

Limited issue for test purposes.

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


<subhead title="0.14 (04 July 2009)">

<list>
<li>Fixed serious bug when pasting more than 128 characters by RAM Transfer, identified by Fred Graute.
</list>


<subhead title="0.15 (05 July 2009)">

<list>
<li>Date insertion now works correctly with custom format strings.
</list>


<subhead title="0.16 (20 January 2012)">

<list>
<li>Fixed unaligned memory access in <key>Ctrl-S</key> and <key>Ctrl-D</key> routines.
</list>


<subhead title="0.17 (01 September 2014)">

<list>
<li>Fix error handling for <command>*Desktop_IcnClipBrd</command>.
</list>


<subhead title="0.20 (29 August 2020)">

<list>
<li>Change the use of <command>*IcnClipBrdKeys</command> to allow shortcut keys to be changed.
</list>

</chapter>

<literal mode="Text">

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
</literal>
