RISCOS Ltd                                                         RISCOS Ltd

                 ------------------------------------------
                 TECHNICAL NOTE: CLIPBOARD PROTOCOL CHANGES
                 ------------------------------------------


   Document: 20000314-001
  
    Version: 1.00 (07 Feb 2000) JRF: Written after extensive testing
             1.01 (08 Feb 2000) JRF: Addenum about nc/Clipboard.html
             1.02 (09 Feb 2000) JRF: Note on responding to DataRequest
             1.03 (14 Mar 2000) JRF: Note on responding to DataSave
                                JRF: Note on responding to ClaimEntity

  Author(s): Justin Fletcher (justin@riscos.com)



1) SPECIFICATION CHANGE FOR CLIPBOARD PROTOCOL (APPNOTE 240)

Applicability:

All Clipboard Applications


Description:

The appnote describes that :
  
   To improve performance, the following optimisation should be made:
   
   When claiming the input focus or clipboard, a task should check to see if
   it already owns that entity, and if so, there is no need to issue the
   broadcast.  It should then take care of updating the caret / selection /
   clipboard to the new value (updating the display in the case of the
   selection).

These paragraphs should be ignored. The implementation described negates any
possibility of identifying the 'natural filetype' of the clipboard. This, in
turn, prevents support for a dynamic clipboard viewer.


Recommendation:

Always broadcast the message whenever you copy or cut to the clipboard.


2) MESSAGE PROTOCOL CLARIFICATION

Applicability:

All Clipboard Applications


Description:

Within the data request message, window, x and y are described to be the
window handle and coordinates within that window. Some applications may not
have such a position to paste into (in the instance of document creation).
Under these circumstances we recommend a window handle of 0. x and y may be
any other private information required.

Recommendation:

Copy the window, icon, x and y parameters from the originating message and
apply no meaning to them.



3) ADDENUM/ERRATA FOR NC/CLIPBOARD.HTML

Applicability:

All Clipboard Applications based on the NC Clipboard 'ReleaseEntity' call.


Description:

This document, previously issued by Acorn for NC developers is now actively
encouraged. However, there appears to be some confusion about how tasks
should reply to messages.

Recommendation:

The documentation of 'replying to the window in the DataSave block' should be
ignored. You should always reply to the sender of the message as held at
block+4. With most applications, this will mean a simplification of any
support written to the method described in that document. It is believed that
there are only a few applications supporting ReleaseEntity, and that most
will have ignored the notes given on this particular method of replying as it
is contrary to general practices.





4) RESPONDING TO DATAREQUEST

Applicability:

All Clipboard Applications.


Description:

DataRequests include a list of known filetypes to which you should respond
with the first you can supply. If none match, you should supply the clipboard
in your natural (native) format. Some applications ignore the request for
the clipboard data in 'any' format. Consequently a clipboard viewer is made
impossible by such applications.

Recommendation:

If you don't recognise any filetypes in the list, save the data in the format
which your application naturally saves data. If it does not have a natural
file format then you should either save in a format that the data was loaded
in, or provide it as 'Data'.




5) RESPONDING TO DATASAVE

Applicability:

All clipboard applications.


Description:

DataSaves in reply to a DataRequest will have a filetype associated with them
which indicates what type the data will be transferred in. It is at this
point that an application should say that it has no knowledge of how to
transfer that type of file.

Recommendation:

On receipt of a DataSave the application should decide, based on the
filetype, window and private data supplied, whether it wishes to load the
file. If it does not wish to load the file it should not attempt to load it
and should present the user with a message saying that there is no method of
transferring the data in that format.




6) RESPONDING TO CLAIM ENTITY

Applicability:

All clipboard applications.


Description:

ClaimEntity (for the clipboard) is broadcast to notify interested parties that
the clipboard is now owned by another application. Any application replying to
this message will prevent other applications from seeing the clipboard claim.


Recommendation:

Never reply to ClaimEntity. If an application wishes to identify whether the
clipboard is of interested to it it should initiate a new message.


-- 
Comment: Clipboard protocol technote
Part: 20000314-001