|
WindowManager 'Cut and Paste'
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 affect 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 :
| 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-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 :
- 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 via the standard RISC OS clipboard. This is to prevent sensitive information being exposed by copying to a visible icon or editor. Selections may, however, be pasted to such icons.
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. 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 (SWI &400D3)
On entry
R0 = &4B534154 ("TASK")
R1 = pointer to a description block
R2 = operation type:
0 = read caret position
2 = read selection position
Other values reserved
On exit
R0 corrupt
This extended form of the Wimp_GetCaretPosition SWI can be used to read the caret or selection position.
Wimp_GetCaretPosition 0 (SWI &400D3)
On entry
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 writable icon
R2 = 0 (read caret position)
On exit
R0 corrupt
This extended form of Wimp_GetCaretPosition mirrors the standard call, but in the new format.
Wimp_GetCaretPosition 2 (SWI &400D3)
On entry
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)
On exit
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 (SWI &400D2)
On entry
R0 = &4B534154 ("TASK")
R1 = pointer to a description block
R2 = operation type:
0 = set caret position
2 = set selection position
Other values reserved
On exit
R0 corrupt
This extended form of the Wimp_SetCaretPosition SWI can be used to read the caret or selection position.
Wimp_SetCaretPosition 0 (SWI &400D2)
On entry
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 calculate from x and y
R2 = 0 (set caret position)
On exit
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 (SWI &400D2)
On entry
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)
On exit
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 (SWI &400D0)
On entry
R1 = pointer to block :
+0 = -1
+4 = 13
On exit
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 (SWI &400F2)
On entry
R0 = 21
R2 = 1
On exit
R0 = text selection background colour, or -1 if selection colours disabled
R1 = text selection foreground colour if R0 = -1
R2 = text selection flags:
bit 0 - Text selections are enabled
bits 1-2 - Operation on text insert:
0 = no operation, leave selection alone
1 = delete selection
2 = clear selected region
3 = cut selection
bits 3-4 - Operation on text delete (as above)
bits 5-6 - Operation on caret move within icon (as above)
bit 7 - Auto-select text on caret entering icon
bits 8-31 - reserved for future expansion
This SWI is used to read the text selection colours and flags, as defined with *WimpTextSelection. The text selection colours are used for selections of text made by the user in writable 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.
Under some versions of the WindowManager the flags were not returned in R2 with this call and it is therefore necessary to supply a sensible default in R2. It is recommend that R2 be set to 1 to indicate that text selections are enabled.
Wimp_CommandWindow
From Select 1 onward Wimp_CommandWindow has been extended to provide information about its current state. This information can be used to determine whether or not an operation will trigger the display of a command window.
Under normal circumstances, when a task is started by the Window Manager the command window is marked as 'pending'. In this state, any output to the screen through the standard VDU calls will cause the command window to be opened; the state will then be set to 'open'. If the task registers with the Window Manager with Wimp_Initialise however, the command window is marked as 'inactive'. These states can be changed through the use of Wimp_CommandWindow as described in the PRMs.
The new call allows clients to identify what state the command window is currently in.
Wimp_CommandWindow
On entry
R0 = 2 (Read state)
On exit
R0 = 0 if the command window is inactive
1 if the command window is pending
2 if the command window is open
This SWI is used to find the state of the command window.
Wimp screen edge notifications
When the pointer idles at the edge of the screen a message is sent to all tasks. At present this message relies on the iconbar toggle being enabled. Future versions may not have this restriction.
Message_ScreenEdgeNotification (&400D2)
R1+16 = &400D2
R1+20 = bit mask :
0 = left of screen
1 = bottom of screen
2 = right of screen
3 = top of screen
Others reserved
This message is sent by the WindowManager when the pointer idles over the edge of the screen. It is intended that shortcut applications might use this to activate themselves.
Wimp_Extend 257
On entry
R0 = 257
R1 = pointer to filename in a buffer to be updated
On exit
R0 = pointer to buffer passed in
R1 = 0 (if buffer updated, preserved if not supported by this Wimp)
This SWI is used to append a mode suffix to a filename within a buffer. The buffer should have space for up to 8 characters in addition to the filename in order to allow for future expansion. The suffixes follow the standard pattern of describing the pixel sizes in terms of OS units (see Wimp_ReadSysInfo 2 in PRM 3-218).
Initially, the current mode suffix will be tried. If this does not exist, the name will be normalised to the lowest pixel size. If the suffix is 11 and this fails then 22 will be tried. If these fail, then the call will fall back to no suffix. For example, in a mode with pixels using the size 1 OS unit in the x direction and 4 OS units in the y direction (eigen factors EX0 EY2) the suffixes examined would be 14, 24, 44 and finally falling back to no suffix.
Clients should check whether R1 has been set to 0 on return. If it has not, this call is not supported by the WindowManager.
Note: Under Select 3i1 this call was Wimp_Extend 14 but this was found to clash with an undocumented call under RISC OS 5. It has been reallocated.
Wimp_Extend 258
Read colourmap translation for rendering sprite
On entry
R0 = 258
R1 = flags :
bits 0-20 - reserved, must be 0
bit 21 - translation is for selected item
bit 22 - translation is for faded item
bit 23 - translation is for when pointer over item (N/I)
bits 24-27 - wimp foreground colour for icon (if not in validation)
bits 28-31 - wimp background colour for icon (if not in validation)
R2 = window handle, or -1 to use grey 1 as background colour
R3 = pointer to validation string to use, or -1 for none
R4 = background colour &BBGGRR00, or -1 for window colour
On exit
R0 = pointer to colourmap descriptor :
+0 workspace for translation function
+4 pointer to translation function
This SWI is used to read the colourmap translation function for a sprite operation. It should be used where a sprite (or other object) needs to be rendered using the same colour mapping as the Wimp would use. In general it may be better to use Wimp_PlotIcon, but where this is not feasible - for example where additional colour mapping is required, or the user wishes to cache results - this call can be used to obtain the relevant colour mapping function.
The descriptor returned is valid until the next Wimp icon, sprite or window operation, or another call to this function. It is recommended therefore that it only be used by the foreground application and never by transient callback code.
The validation string may contain 'C' or 'T' validations to indicate the state of the image being rendered.
|
![[Select]](../../imgs/seldoc.png)
