Introduction
The WindowManager has been updated to support cut and paste between writable 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 effect on existing applications. The Selection is indicated by inverted text within a writable 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 :
| Keys | Action |
|---|---|
| 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 (SWI Wimp_GetCaretPosition) to read the selection indices, make their changes, modify the selection indices appropriately, and call the second new Selection SWI (SWI Wimp_SetCaretPosition) to reassert the selection.
As with the Caret, the Selection can be placed in non-writable icons through the use of Wimp_SetCaretPosition. The behaviour outside of writable 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 four types 'Insert', 'Delete', 'Move', '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.
- 'Move' operations are those which cause the caret to move within the icon.
- 'Control' operations are all other keyboard controls, such as cursor keys moving out of the icon and function keys.
'Control' operations never affect the selection by themselves. The effect of 'Insert', 'Delete', or 'Move' operations can be controlled through the *WimpTextSelection command, allowing four different effects :
| Effect | Meaning |
|---|---|
| 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. |
It is not expected that it will be useful to apply the 'delete' or 'clear' effects on the 'Move' operation. The ability to change the 'Move' operation allows a similar scheme of text selection methods as that used on other operating systems.
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.
Multi-line ('L' validation)
Icons with the 'Multi-line' validation token present cannot be copied from through the standard RISC OS clipboard. Multi-line writable icons are not reliable in current versions of the WindowManager and will result in undesirable graphical effects. Attempts to set a selection within such icons will be ignored.
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 writable 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
It is recommended that applications which provide clipboard functions of their own in writable icons under earlier versions of the WindowManager should disable those clipboard or selection operations when run under WindowManager versions capable of providing the Selection. Applications should use the SWI Wimp_ReadSysInfo 15 call to detect whether the WindowManager is capable of using the Selection; the call returns an error if it is not.
SWI Calls
| R0 | = | &4B534154 ("TASK") | ||||||||
| R1 | = | Pointer to a description block | ||||||||
| R2 | = | Operation type:
|
| R0 | = | Corrupted |
This extended form of the Wimp_GetCaretPosition SWI can be used to read the caret or selection position.
| R0 | = | &4B534154 ("TASK") | ||||||||||||||
| R1 | = | Pointer to a description block:
| ||||||||||||||
| R2 | = | 0 (read caret position) |
| R0 | = | Corrupted |
This extended form of Wimp_GetCaretPosition mirrors the standard call, but in the new format.
| R0 | = | &4B534154 ("TASK") | ||||||||||
| R1 | = | Pointer to a description block:
| ||||||||||
| R2 | = | 2 (read selection position) |
| R0 | = | Corrupted |
This extended form of Wimp_GetCaretPosition gives access to details about the selection. The indices of the selection are byte indices into the string.
| R0 | = | &4B534154 ("TASK") | ||||||||
| R1 | = | Pointer to a description block | ||||||||
| R2 | = | Operation type:
|
| R0 | = | Corrupted |
This extended form of the Wimp_SetCaretPosition SWI can be used to set the caret or selection position.
| R0 | = | &4B534154 ("TASK") | ||||||||||||||
| R1 | = | Pointer to a description block:
| ||||||||||||||
| R2 | = | 0 (set caret position) |
| R0 | = | Corrupted |
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.
| R0 | = | &4B534154 ("TASK") | ||||||||||
| R1 | = | Pointer to a description block:
| ||||||||||
| R2 | = | 2 (set selection position) |
| R0 | = | Corrupted |
This extended form of Wimp_SetCaretPosition 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.
| R1 | = | Pointer to block:
|
| R0 | = | Corrupted |
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.
Related interfaces
The text selection settings are read with SWI Wimp_ReadSysInfo 15, described in the Wimp_ReadSysInfo document. The state of the command window can be read with Wimp_CommandWindow, the pointer idling at the screen edge is reported by Wimp screen edge notifications, and the extended calls Wimp_Extend 257 and Wimp_Extend 258 are described in their own documents.