WindowManager 'Cut and Paste'
=============================

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

The WindowManager has been updated to support cut and paste between
writeable icons, as well as allowing partial text selections to be made.
This facility is intended to be used in conjunction with the standard RISC
OS Clipboard protocol. The ClipboardHolder module provides the external
interface to the clipboard used by the WindowManager, as well as providing
the same facilities for other clients.

Overview
--------
The WindowManager provides a selection model which is simple to use and
should not have a detrimental affect on existing applications. The Selection
is indicated by inverted text within a writeable icon. The bounds of the
selection can be made through either the keyboard, or mouse selection
methods. Using the keyboard, the following key combinations can be used :

  Shift-Ctrl-Left - extend selection to the character to the left of the
                    current position and move left
  Shift-Ctrl-Right - extend selection to the character to the right of the
                    current position and move right
  Ctrl-C - Copy the selection to the clipboard
  Ctrl-V - Paste the clipboard to the current position
  Ctrl-X - Copy the selection to the clipboard and delete it ('cut')
  Ctrl-A - Select the entire icon's text
  Ctrl-Z - Clear the selection

Within the icon, the caret may move either through mouse clicks or the use
of the left or right cursors (in combination with shift or ctrl). Whilst the
selection is present, text input into the icon can be configured to extend
the text, maintaining the selection, to clear the selection, to cut the
selection, or to delete the selected text.

The mouse can be used to make selections by clicking at the start position
and holding down the mouse whilst moving over the string. The selection may
be modified by clicking the adjust button over the string. If no selection
is present, adjust may be used to create a selection between the caret and
the position clicked. These selection operations are automatically provided
by the WindowManager if none of the modifier keys (Shift, Ctrl, Alt) are
pressed.


Technical details
-----------------

 ClipboardHolder
 ---------------
The ClipboardHolder module handles the Clipboard protocol negotiations with
other tasks and attempts to take control of any text (type &FFF) files which
are placed on the clipboard. This allows the ClipboardHolder to provide this
information directly to the WindowManager.

 Selection and Caret
 -------------------
The Selection and the Caret are 'tied' together. The selection can only
exist in an icon which has the Caret. Moving the Caret away from the
selection will cause the Selection to be deselected. Changes to the icon
outside the control of the WindowManager (which are indicated by a
Wimp_SetIconState call) cause the Selection to be deselected. Tasks wishing
to retain the selection over a change to the icon should call the new
Selection SWI (Wimp_GetCaretPosition) to read the selection indices, make
their changes, modify the selection indices appropriately, and call the
second new Selection SWI (Wimp_SetCaretPosition) to reassert the selection.

As with the Caret, the Selection can be placed in non-writeable icons
through the use of Wimp_SetCaretPosition. The behaviour outside of writeable
icons (type 14 or type 15) is undefined and may change in future versions
of the WindowManager.

 System font
 -----------
The System Font is not presently supported for making selections. This may
be addressed in a future version.

 Keyboard input
 --------------
If keyboard input is used whilst the selection is present, this can be
configured to perform different operations. Keyboard input operations are
divided into three types 'insert', 'delete', 'control'. 'Insert' operations
are those which cause text to be inserted into the icon. 'Delete' operations
are those which cause text to be deleted from the icon. 'Control' operations
are all other keyboard controls, such as cursor keys and function keys.
'Control' operations never affect the selection by themselves. The effect of
'insert' or 'delete' operations can be controlled through the
*WimpTextSelection command, allowing four different effects :
   none - the text is inserted or deleted as normal and the selection is
          unchanged.
   delete - the selection is deleted and the character typed is inserted.
   clear - the selection is forgotten and the character typed is inserted
   cut - the selection is cut to the clipboard and the character typed is
         inserted.

 Validation strings
 ------------------
  
  Passwords ('D' validation)
  ------------------------------
Icons with the 'Display' validation token present cannot be copied from
through the standard RISC OS clipboard. This is to prevent sensitive
information being exposed by copying to a visible icon, or editor.
Selections may be pasted in to such icons however.

  Key notification ('KN' validation)
  ----------------------------------
Icons with the 'Key' validation indicating that the application should be
notified about all key presses events would, under earlier versions of the
Window Manager, exhibit odd behaviour when input was generated from a
function key expansion. This problem was also apparent when input was pasted
into icons. Key input is now buffered and should eliminate the race
condition caused by the insertion of multiple keys into the buffer. This
should allow both function keys and pasted text to be inserted reliably.

  Clipboard prevention ('KC' validation)
  --------------------------------------
A new validation sequence for the 'Key' validation has been added. The
character 'C' within a Key validation indicates that no clipboard operations
should take place on the icon. By default all writeable icons (with the
exception of Password icons as described above) accept the selection and
clipboard key and mouse events as described in the Overview. When this
validation is present, the operation of this icon reverts to that provided
by a non-clipboard enabled WindowManager.

The selection can still be manipulated with Wimp_GetCaretPosition and
Wimp_SetCaretPosition, but the application controls the icon completely.

 Applications already supporting clipboard operations
 ----------------------------------------------------
Applications which provide clipboard functions of their own in writeable
icons under earlier versions of the WindowManager are recommended that they
should disable those clipboard or selection operations when run under
WindowManager versions capable of providing the Selection. Application
should use the Wimp_ReadSysInfo 21 call to detect whether the WindowManager
is capable of using the Selection, returning an error if it is not.


 SWIs
 ----

Two SWIs have been extended to allow access to the Selection.

Wimp_GetCaretPosition
=> R0 = &4B534154 ("TASK")
   R1 = pointer to a description block
   R2 = operation type:
          0 = read caret position
          2 = read selection position
        other values reserved
<= R0 corrupt

This extended form of the Wimp_GetCaretPosition SWI can be used to read
the caret or selection position.

Wimp_GetCaretPosition 0
=> R0 = &4B534154 ("TASK")
   R1 = pointer to a description block :
          +0 = window handle, or -1 if off
          +4 = icon handle, or -1 if background
          +8 = x offset of caret (relative to work area origin)
         +12 = y offset of caret (relative to work area origin)
         +16 = caret height and flags, or -1 for not displayed
         +20 = index of caret into string if in a writeable icon
   R2 = 0 (read caret position)
<= R0 corrupt

This extended form of Wimp_GetCaretPosition mirrors the standard call, but
in the new format.


Wimp_GetCaretPosition 2
=> R0 = &4B534154 ("TASK")
   R1 = pointer to a description block :
          +0 = window handle, or -1 if no selection present
          +4 = icon handle
          +8 = low index of selection
         +12 = high index of selection
   R2 = 2 (read selection position)
<= R0 corrupt

This extended form of Wimp_GetCaretPosition gives access to details about
the selection. The indices of the selection are byte indices into the
string.


Wimp_SetCaretPosition
=> R0 = &4B534154 ("TASK")
   R1 = pointer to a description block
   R2 = operation type:
          0 = set caret position
          2 = set selection position
        other values reserved
<= R0 corrupt

This extended form of the Wimp_SetCaretPosition SWI can be used to read
the caret or selection position.

Wimp_SetCaretPosition 0
=> R0 = &4B534154 ("TASK")
   R1 = pointer to a description block :
          +0 = window handle, or -1 to turn off
          +4 = icon handle, or -1 for icon background
          +8 = x offset of caret (relative to work area origin)
         +12 = y offset of caret (relative to work area origin)
         +16 = caret height and flags, or -1 to calculate from x and y or index
         +20 = index of caret into string, or -1 to calculated from x and y
   R2 = 0 (set caret position)
<= R0 corrupt

This extended form of Wimp_SetCaretPosition mirrors the standard call, but
in the new format. This allows it to be used more easily after a
Wimp_GetCaretPosition call.

Wimp_SetCaretPosition 2
=> R0 = &4B534154 ("TASK")
   R1 = pointer to a description block :
          +0 = window handle, or -1 to lose selection
          +4 = icon handle
          +8 = low index of selection
         +12 = high index of selection
   R2 = 2 (set selection position)
<= R0 corrupt

This extended form of Wimp_GetCaretPosition sets the selection position. The
indices of the selection are byte indices into the string. The high index
should not exceed the length of the string and the low index should not be
negative. The indices start at 0. The low index is inclusive, and the high
index is exclusive, thus a selection with low=2 and high=4 would comprise
the 3rd and 4th characters of the string.

Wimp_DragBox 13
=> R1 = pointer to block :
          +0 = -1
          +4 = 13
<= R0 corrupt

This form of Wimp_DragBox should be used to initiate a 'Text Selection'
operation on the icon containing the caret. Because the text selection
cannot take place on any icon but that with the caret, the 'window handle'
usually held at R1+0 is not used. If Select was used prior to this call,
the selection will be started. If Adjust was used prior to this call, the
selection will be adjusted (or started with the region between the mouse
pointer and the caret).

On earlier systems, this call will generate an error.


Wimp_ReadSysInfo 21
===================
=> R0 = 21
<= R0 = text selection background colour, or -1 if selection colours disabled
   R1 = text selection foreground colour if R0 = -1

This SWI is used to read the text selection colours defined with
*WimpTextSelection. The text selection colours are used for selections of
text made by the user in writeable icons. Applications drawing text
themselves (without the WindowManager's interaction) may need to read the
settings with this call in order to ensure that it follows the users
configured choices.
