Specification
=============

The specification covering the use of cut-and-paste and drag-and-drop in
writable icons is stored
  https://www.riscosopen.org/wiki/documentation/show/Drag-And-Drop%20Functional%20Specification


WindowManager changes - Clipboard
=================================

In order to provide clipboard functionality, the Wimp has had some extra internal functionality added.  Most of the extra calls will be of no major use to other tasks but documentation is supplied here for completeness.  Key press handling changes may be relevant, however.

Key press handling
Certain extra key codes are intercepted and handled by the Wimp if the caret is in a writeable icon.
^C	Copy selection to clipboard
^K	Delete selection
^V	Paste selection from clipboard
^X	Cut selection to clipboard
Shift ^ left cursor	Extend / shrink selection to the left*
Shift ^ right cursor	Extend / shrink selection to the right*
* actual end of the selection that is adjusted depends on which part was last adjusted by the user.

If ^C is used in a password icon, no copy is made.  Similarly, if ^X is used, no data is copied to the clipboard.

Should a task wish to receive these key codes for its own uses, then the above can be blocked by using the validation string KC.  No clipboard selection actions will then take place.


SWIs
====

Wimp_Autoscroll (&400FD)
If bit 3 of the flags in R0 is set, then:
R0	flags
	bit 0: 1=>enable horizontal scrolling; 0=>cancel scrolling
	bit 3: set
	All other bits ignored and should be considered reserved and set to 0.
R1	Pointer to data block
	+0	Window handle
	+4	Icon handle

On exit, registers preserved.  On error, V set and R0 points to standard error block.

This call triggers autoscrolling of a writeable icon.  It is used by the Wimp when a drag operation is in progress to scroll the icon when a ghost caret is being positioned.

Wimp_DragBox (&400D0)
Parameters unchanged.
Drag Box block in R1:
	+0	Window handle
	+4	13
	+8-52	unused

Drag box type 13 has been added.  Issuing this call will start a selection drag within an icon.  The drag is performed on the icon which currently holds the caret.  The exact type of selection drag depends on the last click event on the icon.

Wimp_Extend (&400FB)
There is an extra reason code added.  It is primarily intended for internal use.

R0	14
R1	Window handle
R2	Icon handle
R3	Pointer to buffer for data if R4<>0
R4	Buffer size or 0 to get required size

On exit, if there is an error then R0 points to a standard error block and V is set.
R4	Space remaining in buffer.  Will be negative if R4=0 on entry.

Unlike an indirection string there is no direct way of obtaining the length of an icon validation string from another task.  This call allows a copy of the validation string to be obtained safely.

The buffer pointed to in R3 must not be in application space as it is very likely to be paged out.  If there is not going to be enough space in the allocated buffer then nothing will be copied and the potential overflow count is returned.

This call should be used twice.  On the first call, R4 should be set to 0.  On exit, R4 will contain 0 if there is no validation string or a negative number of characters to indicate the buffer size required.  R3 is ignored in this case.

On the second call, R3 should point to the newly allocated buffer of correct size and R4 gives the positive buffer size.  The validation string is now copied.

Wimp_StartTask (&400DE)
There is a minor change to functionality.
If R0 on entry points to the module title string and the WindowManager task is not running, then the WindowManager task is started.
If any other task is started and the WindowManager task is not running, then the WindowManager task will also be started.

Wimp_SetCaretPosition (&400D2)
Implementation is the same as the Drag and Drop specification but with the addition of one extra variation.
Normally, an icon caret may be set to a particular coordinate by using:
R0	window handle
R1	icon handle
R2	X offset relative to work area origin
R3	Y offset relative to work area origin
R4	undefined
R5	-1

However, R4 is undefined and could be anything.

The additional functionality allows a ghost caret to be set to an icon by using a coordinate rather than a string index:
R0	window handle
R1	icon handle
R2	X offset relative to work area origin
R3	Y offset relative to work area origin
R4	Caret flags
	bits 0-15	caret height in OS units
	24		use a Wimp-drawn caret rather than the Font Manager caret
	30		1 (for ghost caret)
	All other bits should be 0
R5	-2


Message passing
===============

In order to enable clipboard and drag and drop functionality, the Wimp will intercept and redirect certain messages.  These messages will not be received by their intended destination task but will be handled by the WindowManager task instead.

Message_DataLoad
Message_DataSave
If the destination icon is writeable and the filetype at +40 is TextFile (&FFF) then the message is redirected.

Message_Dragging
If the message is part of a new conversation (ie your_ref=0) and the destination icon is writeable and there is an option of a TextFile (&FFF) in the filetype list at +56 then the message is redirected.

Note that it is the reponsibility of each task to bounce Message_Dragging if they currently have a claim and the pointer moves over one of their writeable icons.  A new conversation will then result and the Wimp will perform the interception.  Once the pointer leaves the writeable icon, Message_Dragging will again be bounced and the original task can continue again.


Clipboard Manager task
======================

The Wimp will start up a task called Clipboard Manager if it is not running and another task is started (see Wimp_StartTask above).

The Clipboard Manager task handles clipboard operations and clipboard ownership functionality for the Wimp.  It also handles drag and drop messaging.  It operates as per the drag and drop fucntional specification.


Display buffering
=================

In order to reduce flicker, especially when dragging a selection within an icon, writeable icons are now buffered.  On redraw, the output is written first to a memory buffer and then the resulting buffer is written out to the screen.

The memory buffer is pre-allocated on mode change to cover an icon of 256x26 pixels in size.  Should a larger icon be plotted, then the buffer size will be increased.

Note that there will still be a flicker if there are other icons beneath the writeable icon, as these will be redrawn and then the writeable icon in the usual way.


Memory usage
============

The clipboard Wimp requires extra memory to hold the display buffer and any clipboard or drag and drop data.

If dynamic areas are supported, then this memory is held in a dynamic area which is limited to 8MB in size.  Memory is only claimed for the clipboard or drag and drop if a store is required; the area size will be reduced as far as possible as soon as this usage is over.

If dynamic areas are not supported, then the memory is claimed from the RMA.
